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QUICKTIME 

TOOLKIT 


b)! Tim Monroe 


Event Horizon 


Using Carbon Events in a QuickTime 
Application 


iNTRODlJCnON 

Over the past couple of years, we’ve used a simple 
application, called QTShelL as the basis tor our explorations into 
the QuickTime APIs. QTShell provides the basic Macintosh or 
Windows application sej-vices {start-up, shut-down, event or 
message handling, menu and window management, and so 
fonh), and it provides stub routines that we use for our 
application-specific code. Kor instance, in the previous 
QuickTime Toolkit article (“Big'', in MacTecb April 2002), we saw 
how to add code to QTShell to allow it to play movies riillscreen. 

The main proldem with QTShell as it stands today is that 
its Macintosh code uses an event-handling model that is almost 
20 years old and sorely in need of a tune-up. Our Macintosli 
code is indeed already fully Carbtmi/.ed; that is, it uses only 
Carbon APIs and hence can run both under ""classic" Macintosh 
.systems that support Carhonlib (Mac OS H and 9) and under 
Mac OS X. But it still uses a couple of APIs that result in less 
than optimal performance, especially under Mac OS X. In 
particular, it calls WaitNextEvent to retrieve events for the 
application, and it uses Modal Dialog to handle events while its 
About box is displayed to the user. 

What’s wrong with WaitNextEvent and ModalDialog is that 
they continually poll the operating .system to see whether any 
events have arrived for the application. If our application i.sn’t 
doing anything (for instance, no movies are playing and the user 
has gone to get a cup of coffee), we are wasting valuable 
processor time that could be used by other open applications. It 
would he better if the operating .system would just inform us 
when an event arrives for our application. This is the 
fundamental idea behind the Carbon Event Manager 

In this article, we re going to learn how to replace our calls 
to the “classic” Event Manager with calls to the Carbon Hvent 
Manager. As well see, this mostly involves writing a few eimii 
callback functiom (or eimit bandkn) that are executed when 
specific types of events occur. In effect, tjtir application is 


transformed from a nagging kid (“are w'e there yet?", “are w^e 
there yet?’’...) into a polite child who waits patiently for 
instructions. Well also need to write a Carbon event loop timer 
cailhack function, to allow us to call MCldle periodically to task 
our open movies. (To task or idle a movie is to grant its data 
handlers and media handlers some time to do their work.) Now 
in fact this obviates some of tlie good work we did in moving 
away from WaitNextEvent, since the ("arlion event loop timer is 
going to fire periodicaliy even tf our application has no work to 
do. (The nagging child has been replaced by a nagging pareni: 
""clean your room!”, ""clean your room!”.,.,) We can work around 
thi.s by tLsing the motk tasking inten'al func'iions — new to 
Quicklime 6 — to detemiine when our application should next 
call MCldle; we can then reset the event timer accordingly. 
Toward the end of this anicle, we II also see hfw to work with 
the Cafixrn movie control, a ctisloni ct>ntrol introduced in 
QuickTime 6 that we can use in Carbon applications on Mac OS 
X to display and control movies. The Carbon movie control 
automatically liandles all the event and tasking interval 
management associated with displaying a movie in a window 
and hence frees us from liaving to WTite callback functions or 
timer routines for tliis, Very nice. 

A few' worcis of caution before we i)egin: tlie Carbon movie 
control provides an elegant way to put a QuickTime movie into 
a window, but it’s available only under Mac OS X and only under 
QuickTime 6 or later; as a result, we’ll retain our existing code 
for managing movies and isolate the new code with the 
USE_CARBONjMOVlE._CONTROL compiler Hag. Similarly, we’U 
use the USE_TASK_MGMT compiler flag to set off the code that 
uses QuickTime'.s new tasking interval management APIs. In 
both cases, we really ought lo replace the compiler flags with 
run-time checking of the system software and QuickTime 
version.s and just do the right thing. I’ll leave that refinement as 
an exercise for the reader. 

More imponantly, we still want to be able to build non* 
Carbon versions of QTSlieil-based applications and versions that 
don’t u.se Carbon events, (These can sometimes be useful, for 
instance, in tracking down bugs.) So we'll introduce yet a third 
new compiler flag, USE_CARBON_EVENTS, to enclose the code 
tliat handles Carbon events. We run the risk of ending up with 


Tim Monroe in a niember of die QuickTime engineering learn. You can contaei him at monroe@app I e.com . The views expressed here are not 
necessarily shared by his employer. 


QtricKTiME Toolkit 


MacTTech • May 2002 












M 




|| 


S' 




Roy Fox, Founder, Fox Clocks, Hollis, Nffaino 
One of 400,000 MITOS software users 


I’d rather create clocks than invoices. 

If I wanted to keep books all day, Vd have been an accountant. 


MIYOB 

Small Business. 
Smart Solutions."^ 

AccoiintEdge on the Mac. 
Software includes QuickSooks"' conversion 
utility. MYOS also offers convereion service. 

6 0 0,3 2 2. M YOB 
myob .00 m/us 

f'OtJicfcaoDksJ& s tractemaffc DT tniuft Inc. 


MYOB software is the simplest, most powerful, most complete 
solution for managing my company on the Mac, from the day to day 
to the bottom line. 


Antique frames. Quartz movements. ThaVs my business. 

MYOB software works tor me. 





unreadable code with all thes?e flags, but in fact the damage is 
fairly minor Indeed, seeing the Carbon Event Manager code 
side-by-side with the corresponding "classic” Event Manager 
code can be instaictive, as we’ll soon see* 

Carbon Events Overview 

Let's think back to 1984. The Macintosh operating system 
popularized the idea of eveni-dritfen programming, where an 
application is structured so that it is guided by events reporting 
the user’s actions witli the mouse and keyboard (and other 
occurrences in the computer). An application is driven by its 
event bop, a section of code that retrieves events from the Event 
Manager and dispatches them to the appropriate event-hand ling 
routine. Listing 1 shows a typical event loop. 

listing 1: Retrieving and dispatching events 

QTTramc_Ma i aEvt ntLoop 

static void QTFranieJiainEventLoop (void) 

I 

EveutKecci rd myEvent; 

long myDuration = kWNEMinlmuniSleep: 

vlille (! gShuttlngDcwn ) [ 

// get the nexi event in the queue 

WaitNextEvent [everyEvsnt ♦ SmyEvent, myDuration * NULL} :; 

// handle tJic event 

QTFrame_HandleEverit (limyEvent) i 

] 

1 

We call WaitNextEvent to retrieve an event from the Event 
Manager and then QTFrame_HandleEvent to handle tlie event. 
Hie myDuration parameter to WaitNextEvent specifies the numlxT 
of ticks our appLication is willing to suspend processing if nt> 
events (other than null events) are pending for it. This allows 
other applications and services lo use the processor while we 
don’t need It* If an event arrives ft)r our application before the 
specified duration elapses, WaitNextEvent returns immediately 
with that event* Otherwise, when the duration elapses, 
WaitNextEvent returns with a null event* We can u.se this steady 
stream of null events as a trigger lo perffirm periodic actions* 
The QTFrame^HandleEvent function is essentially a big 
switch statement that branches on the type of the event; 

switch CtheEvent->what) [ 
case mouseDown: 

// liandle mouse4own cvcntfi hca^ 
break: 

ease updateEvt: 

// hmdte update events Iiea" 
break: 

// cases for other event types 

case nullEventJ 

// handle null events here 
break: 

When we throw QuickTime into the mix, we need lo 
make a very simple adjusiment to QTFrame_HandleEventt 
before stepping into the switch statement, well see whether 
the event should be handled by a movie controller attached lo 
one of our open movie windows. We do this by calling 


QTFrame^CheckMovieControllers, which loops though all our 
application's open movie windows and calls MClsPlayerEvent 
until it finds a movie controller that handles the event. So, in 
outline, our event handling function now looks like this: 

isEventHandled " QTl'raiiie_CheckMoYi&CorLtrollers(theEvetit) ; 
if {IsEventHandled] 
return: 

switch [theEvent->what) ( 

I 

The Carbon Event Manager changes this model in several 
key ways. First, as weVe seen, we don't continually poll for 
events by calling WaitNextEvent. Rather, we install one or more 
event callback functions (well see how to do dial shordy); the 
Cariion Event Manager sends particular events directly to those 
callback functions, which then handle the events as appropriate. 
We enable this dispatching by calling RunApplicationEventLoop. 
Listing 2 shows our revised version of QTFrame_MainEventLoop. 

Listing 2: Retrieving and dispatching events (revised) 

QTFnimc_MaiJiEvcniL(x>p 

static void QTFraina_MainEventLoop (void) 

I 

#if aSE.CARBON^VENTS 

RunApplicationEventLoop0i 
Ifelse 

EventRecord myEvent; 

long inyDuration * kWHEMinimumSieep: 

while (IgShuttingDown) [ 

// the next event in the queue 

WaitNextEvBOt(evetyEvent*, femyEi/ent. myDuration, NULL): 

// handle the event 

QTFi:amG_HarLdleE¥Ent (^myKvent): 

I // while (IgSbutlingDowiv) 
j^endif 
I 

RunAppticationEventLoop proce.sses und dispatches events umii 
we call QuitApplicationEventLoop, As you would guess, we call 
QuitAppiicationEventLoop in our application shutdown Function 
QTFrame^QuitFramework, 

The second main change is ihut the Carbon Event Manager 
redellnes the kinds of events our application can receive. The 
original or "classic" Event Manager can handle only a limited 
number of event types; 


eji\m I 

nuilEvent = 0, 

mouseDown ^ 1, 

mouseUp “ 2. 

keyDown = E. 

keyllp = 4. 

autoKey = 5, 

UpdateEvt = 6. 

diskEvt = 7. 

activateEvt = 8. 

nsEvt “ 15. 

kHighLavelEvetit ^ 23 

h 


The Maciniosh sy*stem software folks could of course add 
new event types to this list, but they would be limited to 16 
total event types by the size of the event mask (a l6-bit value 
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that determines which events our application receives when 
it calls WaitNextEvent). 

Tlie Carbon Event Manager uses a much larger set of e%^ents, 
called Carbon events. A Carbon event is uniquely specified by its 
etmit class and its er'ent kind For instance, the Carbon event that 
corresponds to the classic event keyDown is of class 
kEventClassKeyboard and kind kEventRawKeyDown, And the 
Carbon event that corresponds to the classic event updateEvt is 
of class kEventClassWindow and kind kEventWindowUpdate, Here 
are the event classes we shall be concerned w ith in QTShell: 


enum I 

kEventClafl sKeyboard 
kEventClassApplication 
kEventClassMenu 
kEvent Glee sWind□w 
kEventClassControl 
kEvent Class Comma nd 
h 


= FOUR^CtiAR..CODE(-keyb’), 

- FOUR„CHAR„CODE(* appl')* 

= FOUE_CHAk_CODE t * menu‘). 
- FOUR_CHAR^CODE(^wind'). 
= FOUE_CHAR^CODE C * cn11'), 

- F0tJR_CHAF_C0DE(' cmde'} 


But the Carbon Event Manager doesn't just resluifOe the 
classic events into new classes; in addition, it defines a large 
number of new^ kinds tif events. F(}r instance, when the user 
clicks in a windt>w's ckjse box, nur application can receive an 
event of class kEventClassWindow and kind kEventWindowClose. 
Gone are the days when we just got a mt>use click and bad to 
detennine where the click occurred and perhaps then track the 
click until the user released the mouse bution; instead, we get 
higherdevel indications of what the user is trying to accomplish. 
We really don’t care about the mouse-down event; rather, we 
care that the user clicked in the window's close box. 

rhis ties in with yet another significant advantage of the 
Carl’jon Event Manager: it provides default event handlers for 
these event classes. I'he defauli handler for window events, for 
instance, km)ws how' to handle clicks in the close box and the 
zoom box, as well as drag-clicks in the window s title bar. And 
ilie default handler for controls knows how to handle control 
clicks and tracking. Our application needs to get invtdved only 
when we want to override or augment the l>ehaviors provided 
by the default handlers. For instance, before we allow' tlie user 
to do.se a movie window, we need to cheek to see whether any 
of the data in the window' has dvanged and give the user the 
opportunity to .save any changes. So we'll install an event 
hajidler that receives window' dose events. 

We install an event handler by calling InstallEventHandler, tn 
theory, we could write one big event handler for all the event 
classes and kinds we care about, but in practice ils better to 
write one event handler for each type of event target. An eimn 
target is an opaque object that corresponds to an object in the 
application that can receive events, such as a control, a wandow, 
or the application itself, 'fhe Carbon Event Manager provide.s a 
handful of routines for obtaining event targets; for example, w'e 
can cad GetWindowEventTarget to get the event target associated 
w ith a particular window. 

In summaiy^ we implement support Ibr the Carlxm Event 
Manager by defining and installing an event handler for each 
event target our application cares about. Depending on the type 


of target, we may need to explicitly install the default Cor 
standard) event handler. And we make it all go by calling 
RunApplicationEvantLoop, as we saw in Listing 2. 

Document Windows 

As you know, QTShell can open movies and images in 
standard document windows. Well take advantage of the 
default behaviors provided by the Carbon Event Manager's 
standard window event handler and restrict our window event 
handler to those events that have special meaning for 
QuickTime or for our application. 

Specifying Evenfc» 

We specify one or more events by creating an array of event 
type specijications, defined by the EventTypeSpec data type: 

struct EventTypeSpec 1 

GInt32 eventClass: 

UInt32 eventKlnd; 

h 

If a window contains a movie, we need to pass to the associated 
movie controller any key events tlial are not command-key 
events ( which might therefore be menu item shortcuts); we also 
need to pass the movie controller any mouse dicks inside the 
movie rectangle. In addition, our application needs to know 
when the window is being dosed, activated or deactivated, and 
when it needs to be redrawn. We can specify the events that 
.should he sent to our window event handler like this: 

EventTypeSpec rayEventSpec 1 ] = I 

I kEv^ntClaEsKeybca rd, kEventRa^jKeyDovttl. 
ikEventClaGsKf^yboard. kEventRawKeyRepeat ] ♦ 

(kEventClassKeyboard, kEventRawKeyUpI * 

\ kEventClassWindow» kEventWindowUpdateI. 

IkEventClassWindow* kEventWindowBrawContent]* 

(kEventClassWindow * kEventWindovActivatedI, 

(kEventClassWindow* kEventWindowOeactivatedJ * 
tkEventClassWindow* kEveiitWindowHandleContentCliok], 

(kEventClassWlndow * kEventWindowC1ose) 

I: 


Notice that a single event target can receive more than one 
class of event; in this case, our document window event handler 
i,s to be sent both keyboard events and window events. 

Installing Event Handlers 

In our Macintosh code* we create a movie or image window 
by calling NewCWindow. We can attach the standard event 
handler to that new wiridi)w by calling the 
InstailStandardEventHandler function, like this: 

LnstallStandardEventHandler{GetWindowEventTarget(rnyWlndow)); 

The GetWindowEventTarget function returns an event target 
assexiated with the specified window. It’s worth noting that if 
we had called Create New Window to create the window, then we 
should install the standard event handler by setting a window 
anribiite, like this: 

ChangeWindowAttributes {rayWitidow* 

kWindowStandardEandlerAttribute, 0); 
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We use the InstallEventHandler function to install our custom 
window event handler: 

if (gWinEventHandlerUPP {“ HULL) 

InstallEventHandler(GetWindowEventTarget(ntyWindow). 

gWinEventHandlexUPP♦ GetEventTypeCount CmyEventSpec}♦ 
myEventSpec, 

QTFraiiie_GetWindowObJectFrciiatJ±iidow(myWindow). NULL): 


The first parameter is of course the event target — which 
corresponds to our new window. The second parameter is a 
universal procedure pointer to the event callback function, 
which we can create by calling NewEventHandlerUPP: 

EventHandlerUPP gWlrvEventHandlerUPP ^ NULL; 

gWinEventHandlerUPP = NewEventHandlerUPP 

{QTF r ame_Ca r b onEv en tWind owHa n d1e r)t 

The third parameter is the number of event type specifications 
contained in tlie fourtli parameter As you can see, we use the 
Carbon Event Manager function GetEventTypeCount to get that 
number. The fifth parameter is a reference coaslant that is 
passed to the event handler when it is called. In this case, we 
want to pass a handle to the application-specific data attached 
to the window. The last parameter to InstallEventHandter is the 
address of a variable of type EventHandlerRef; this is an opaque 
type that refers to the newly-installed event handler. We don't 
need that reference, .so we pass NULL, 

Listing 3 shows our revised version of 
QTFrame^CreateMovieWindow, 

Listing 3; Creating a mov ie window Crevised)_ 

QTFrajnt:_CfcateMovie Window 

WindowReferente OTFreme^CreateMovieWindow (void) 

I 

WlndowReference myWindow “ NULL; 

// create n new window to di.^play Uic movie in 

inyWindow " NewCWindowtNULL, &gWlndowRect, gWindowTitle, 
false. noGrowDoeProc. {WindowPtr)-IL* true. 0): 

// create a new window t)bject asisociaied with the new window 
QTPraine_CreateWindowbbject (myWlndow) t 

//if USE^CARBON_EVENTS 

! 

EventTypeSpec myEventSpec[1=1 

t kEventClaesKeyboa rd, kEventRawKeyDovn1. 

(kEventClassKeyboard, kEventRawKeyRepeat1, 

!kEvnntClassKeyboard. kEventRawKeyUp1, 

(kEventClassWindow, kEventWindowUpdateI, 
ikEventClassWindow, kEventWindowDrawContent1, 
fkEventClassWindow, kEventWlndowActivatedl. 
ikEventClassWindov, kEventWindowDeactivated1 * 
{kEventClassWindov* kEventWindowHandleContentClickl, 
IkEventClassWlndow, kEventWindovC1oseI 
t; 

// install Carbon ev'ent handlers for this window 
Ins t alIS t a nd a rdEventHandlet 

(GetWindowEventTarget(myWindow)); 
if (gWinEventHandlerUPP 1= NULL) 

InstallEventHandler(GetWindowEventTatget(myWindov), 

gWinEventHandlerUPP. GetEventTypeCDimtCmyEventSpec), 
luyEventSpec ♦ 

QTEraiiie_GetWiiidowObjectEromWindowCi!iyVfindow). NULL): 

/fendif 

return (myWlndow); 

1 
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Handling Window Events 

Now, when the Carbon Event Manager receives an event 
of a kind we want to handle for a document window, it calls 
QTFrame_CarbonEventWindowHandler, which Is declared like 
this: 

PASCAL_RTN OSStatus QTFtaine_CarbonEveiitW±ndovHandler 

(EventHandlerGallRef theCallRef, EventRef theEvent^ 
void UbeKefCon) 

The event handler is passed the reference constant we specified 
when we called InstallEventHandler, as well as an event reference 
and an event handler call reference. The event reference is an 
opaque data structure that contains information alxiut the event, 
such as its class, its kind, and any additional parameters for tlie 
event. We can use the GetEventClass and GetEventKind functions 
to extract the event class and kind from the event reference: 

myCless GetEventClass(theEvent): 
niyKind “ GetEventKind(theEvent}; 

And we can use GetEventParameter to retrieve any additional 
event parameters. For instance, when the event class is 
kEventClassWindow and the event kind is 
kEventWindowHandleContentClick, then the direct object 
parameter is a window pointer for the target window; we can 
retrieve that information like this: 

WindowR^f myWindow = NULL: 

myErt = GetEventParameter(theEvent, kEventParamOirectObject. 
typeWindowRef, NULL, sizeof(myWindow), NULL. 

&myWindow ); 

Recall tliat with the “classic" Event Manager, the amount of 
information associated with an event was limited to what could 
be stuffed into an event retxjrd; with the Carbon Event Manager, 
any number of event parameters can be associated with a 
particular event type. 

The theCallRef parameter passed to 
QTFrame_CarbonEventWindowHand[er is a reference to the next 
event handler in the event handler sequence For tlie ass(x:iated 
event targeL The CarhKin Event Manager arranges handlers into a 
sequence (technically, a stack) and calls each handler in turn until 
one of them handles the event. This scheme allows us to override 
certain behaviors rif a standard event handler but perhaps not all. 
For example, when we receive the kEventWindowClose event, we 
can prompt the user to save (Jr di.scard any changes to the movie 
data in a window and then fall through to the standard event 
handler to actually close the window. (We can avoid this “fall 
through” by returning any result code other than 
eventNotHandledErrJ And if we want to invoke the next event 
handler in the stack be/dre we do our custom processing, we can 
call CallNextEventHandler with the event handler call reference 
passed to our own event handler. In Q't'Shell we won’t use this 
event liandler call reference, since we shall completely handle any 
events we are registered to receive or else fall tlirough to the 
standard handlers. 

Let's take a look at how we handle a few of the events 
targeted at a document window. It turns out that most of these 
events can be direedy translated into classic events and then 


processed using our existing function QTFrame^^HandleEvent. We 
can use the function ConvertEventRefToEventReoord to convert a 
Carbon event into its corresponding classic event: 

Ev entRec o rd inyE vent; 

ConvertEventRefTaEventRecord{tbeEvent, SiuyEvent ); 

CorwertEventRefToEventRecord returns a Boolean value that indicates 
wliedier it successfully converted the Carbon event into a classic 
event; so we can process our keyboard events like this: 

case kEventClassKeyboard: 
switch (myKind) I 

case kEventRawKeyD own: 
case kEventRawKeyRepeat: 
case kEvetitRavKeyUp; 

if (ConvertEventRefToEventRecord[theEventt ^rayEvent)) 

QTFraiiie_HaTidleEvent (tiiDyEvent): 
myErr - noErr: 
break: 

] 

break; 

For some kinds of Carbon events, 
ConvertEventRefToEventRecord doesn't seem to work; in those 
cases, we need to construci an event record ourselves. A 
good example here is the kEventWindowHandleContentClick 
event. We can handle il by explicitly retrieving the relevant 
event parameters and assigning them to the fields of the 
event record, as shown in listing 4. 

Llstifig 4: Handling document window events 

QlTriimc_C^art3i>nKveiitWindowHsuidla' 
PAECAL_RTN OSStatus QTFtaiue^CarbonEventWlndowHandier 

(EveDtHandierCallRef theCallRef, EventRef theEveat. 
void *tbeRefCon) 
t 

(^pragma unused (theCallRef) 

UInt32 myClass, myKind: 

UrTit32 myModifi^rs: 

WindowRef inyWlndov = NULL: 

EventRecord myEvent: 

WlndowObject rnyWindowObject = (WindowObjectitheRafCon: 

OSStatus myErr - eventNotHandledErr: 

myClass = GetEventClass(theEvent): 
myKind = GetEventKlnd (theEvetit) : 

switch (inyClasa) I 

case kEventCiassKeyboatd: 
switch CmyKind) I 

case kEventRawKeyDown: 
case kEventRawKeyRepeat: 
case kEvetitRawKeyUp: 

if (ConvertEventRefToEventRecord(tbeEvent, 

^ayEvent)) 

QTR raiiieJandleEvcnt (^myEvent); 
myErr = noErr: 
break; 
f 

break; 

case kEventClassWindow: 
switch (tayKind) I 

case kEventWindowUpdate: 
caae kEventWlndowDrawConterjt: 
case kEventWindowActivated: 
case kEventWindowDeactivated: 

if (ConvertEventRefToEventRecord[tbeEvent, 

imyEvent)) 

QTFrame_Hand1eEvent{&myEvent); 
myErr - noErr: 
break; 

case kEventWindowHand1eContentClick: 
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Phone; 802-496-7171 
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iiiyErr = Ge t Even t Pa rame t e t: (theE vent. 

kEventParaniDirectObjectK cypeWindowRef, NULL, 
sizeof (niyWindow), NULL* ^yWindov); 
if (myErr = noErr) [ 

GetEventParameter{theEvent * 

kEventParamKeyHodiffers. typeLfInt32 * NULL. 
sizeof (tiiyModifiers), NULL* fiimyModifiers) : 
GetEventPararneter (theEvent, 

kEventParamMoiiaeLocation, typeQDPolnt. NULL, 
sizeof(Point]* NULL, &myEvent.where); 

myEvent.what = mouseDown; 
myEvent.meflsage - {long)iiiyWindow; 
myEvent.modifiers = rayModifiers; 
myEvent.when = EventTimeToTicks{ 
GetCtirtentEventTimeC)): 

QTFrajBe_HandleEYent {fionyEvent); 
myErr = noErr; 

] 

h reak; 

case kEventWindowClose: 

if (myWindowObject t“ NULL) I 
QTE r aiiie_De stroyHovieWitidow[ 

[ * ‘tnyWindowObj ect}, fWindow): 

myErr = noErr; 
break; 

default: 
break: 

break; 


return(myErr); 

! 

Notice that we set the when field of the event rect)rd [)y 
calling GetCurrentEventTime and converting the value it returns 
into licks (using the utility macro EventTimeToTicks); this is the 
Carbon event replacement for good old TickCount. 


Menus 

Currently^ we handle Macintosh menu selections in the 
standard “classic” fashion; we call MenuSelect when we get a 
mouse-down event in the menu bar MenuSolect drops down the 
menus and tracks events in them until the user releases the 
mouse button; then it remrns a 32-bit long integer whose high- 
order 16-bit word is the ID of the menu and whose low-order 
16-bit word is the menu item index. Our function 
QTFrame_HandleMenuCommancl inspects that long integer and 
reacts appropriately. 

On Windows* a menu item is specified by a single l6'bit 
“menu item identified', which is an arbitrary value that we 
associate with the menu item. Because the value on Windows is 
arbitrary* we've constructed it by setting the high-order 8 bits to 
the Macintosh menu ID and the low-order 8-birs to the index of 
the menu item in the menu. Here aa^ the values we use for the 
File menu items: 


WeVe designed our menu-handling functions 
(QTFrame_HandleFiteMenultem* QTFrame^HandleEditMenultem, 
and QTApp_HandieMenu) to accept these l6-bit values* and 
weVe defined several macros to help us construct and 
deconstruct a menu item identifier: 

MENU_IDENTIFIER{raenuID.raenultein) 

[ (metiviID<<8 J + (Benultem)) 
fMefine MENU_ID{3iienuldentifier) 

((ntenuIdentifieriOxf fOO) »8) 
^define MENU_ITEM(ineEuIdeT3tifier) 

((nienuldentlf lerSiOicOOff)) 


The Carbon Event Manager greatly simplifies our menu 
handling. The default application event handler prex'esses all 
events in the menu bar and in menus; our application is called 
only when a menu state needs to be adjusted or when the user 
actually selects a menu item. Notifications of menu selections are 
sent to an application’s event callback function that handles 
command events. The event class is kEventClassCommand and 
the event kind is kEventCo mm and Process, 

DeHning Command IDs 

When our menu event callback function is called, we 
determine which menu item was selected by looking at the 
command ID associated with the event. A command ID is a 32- 
bit value; we are free to associate any value with any menu item* 
but the Carbon Event Manager defines a set of IDs for some of 
the standard menu items. For instance, it defines these constants 
fur the Edit menu items: 

CTiura \ 

kBiCommandUndo 
kU J Co mma n dRedo 
kHIComioandCut 
kin C omman d Copy 
kHICommandPaste 
kHICoraniandClear 
kill C omraand Se I e c t A11 
I: 


= FOUR_CHAR_CODE('imdo*) 

- FOUR^CHAR_CODECredoD 

- FOUR_CHAR_CODECcut *) 
= FOUR_CHAR_CODE{'copyD 

- FOUK_GHAR_CODE{'pastD 

- FOUR_CHAR_CODE(’clea*) 

- FOUR_CHAR_CODE ('sall H 


And the Carbon Event Manager defines this constant for the Quit 
item in the File menu (tin Mac OS 8 and 9) or the Application 
menu (on Mac OS X): 

anum ( 

kHIComraandQuit - FOUR_CHAR_CODE('quit *) 

1 ; 


We’re going to keep using our custom menu item 
identifiers* but we also need to assign command IDs to the menu 
items when w^e are using the Carbon Event Manager. Well 
define the COMMANDJD macro to convert a 16-bit menu item 
identifier into a 32-bit command ID: 


^define IDILFILENEW 33025 

#defitie IDM_FILEOPEN 33026 

i/define 1DM_FILECL0£E 33027 

^define IDM_FILESAVE 33028 

tfdefloe IDM_FILESAVEAS 33029 

tfdafioe IDM_EXIT 33031 


#defIne C0KMANTI_ID(menuIdentifier) 

({MENU_IE (menuldentlfier)«16) ^-{MENU_lTEM(menuIdentifier))) 

When QTShell starts up* we need to call 
SetMenultemCommandlD to associate command IDs with menu 
Items, listing 5 shows the code well call. 
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OmniObjectMeter has not been tested on blowfish 
allergies^ but Jt is the best tool to help you seek and 
destroy memory leaks and expensive aliocation 
operations In your Cocoa programs. 

• Track allocations, references, and deallocations of 
Objective-C, CoreFoundation, and BSD objects In a 
running process. 

« Use our unique matching window to quickly match and 
hide paired reference count changing events. All that 
will be left are leaks, zombies, and retain cycles. 

* Track down and eliminate transient objects, excessive 
autoreleases, and other Inefficient operations. 


-But wait, 

OMNIGRAFFLE 2.0 


THERE'S MORE - 

OmniOutliner 2.0 


Our symbolic drawing application easily generates flow charts, ER models, 
network diagrams, and much more. We think it's the bee's knees. And 
being the overachieving developers that we are, we went and added some 
cool features to OmnICraffle that make our programming lives easier. Now 
with 2.0 weTe sharing them with the world, so your life will be easier too. 
Aren't we just peachy that way? 

Project Builder / Framework Import: drag In a Cocoa 
project or framework to automatically create a class 
hierarchy diagram with clickable links to header files. 

AppleScript Everywhere : use OmniGraffle as an 
Interface for tasks tike bug tracking and scheduling. 

Attach scripts to graphics to make interactive documents; 

Import and layout data from scripiable applications like 
FileMaker. 



OmniOutliner Is a general-purpose outlining and list¬ 
making program; weVe found it has myriad uses In 
software development: bug lists, project schedules, 
pseudocode outlines, etc. Plus a 
few features just for geeks like us: 

"Sample'^ import: presents output from 
Apple's command‘llne "sample" program 
(a useful performance monitoring tool) In 
an easy-to-read hierarchical view. (Just 
remove the “.txt" extension from the 
output hie and open It in OmniOutliner.) 


More AppleScript : 2.0 adds complete AppleScript support, so, for 
example, you can dump your project schedule to OmnlCrafOe. 



if you've bought a Power Mac or PowerBook since January 2002, youVe already sitting In the back of the bus with the cool kids — OmnlGrafTle 1.1 and OmniOutliner 1.2 are already 
Installed In your Applications Folder. But drop by our website and upgrade to the 2.0 versions we talk about here: they're much cooler. 



www.omnicroup.com/mactech 

The Omni Croup 
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Listing 5: Defining the framework command IDs 

QTFram€_liiilMeniiBaT 

#if USE_GARBOK_KVENTS 

myKenu “ GetMenuHand 1 e[kApp 1 eMenuKe sID)^ 
SetMantiItC] 3 iCoi!miandID(iiryMenu. kAboatMenuItem. COMMAHD_IDt 
l1ENlj_IDENTIFIER(kAppleMenuResID.kAboutMenuIteta)}) j 

myMetiu = GetMeniiHaTidlE (kFlleMentiReslD) ; 
EetMenuIteinCQniraandID(niyMenu. MENII_ITEMCIDM_FILENEW). 

COMMAND^ID[TDM.FTLENEW)): 

E etMenu 11 euiG ommaTid 1D (myMenu. MENlJ_I TEM (IDM_F ILEOPEN) , 

COMMAND^ID(IDM_F1LE0PEH)): 

SetMenurteroCoinniandlD (niyMeTiu * MENU_ITEM(IDH_FrLECLOSE) * 

C0HMAND_IDEIDM_FILECL0SE)) i 
EetMenuItemCommandID {tnyMenu. MENy_ITEM(lDM_FILESAVE),, 

COMKAND_ID(IDM,FILBSAVE)); 

SetManuItemCotmiiandlD(myMenu. MEN!J_TTEM(lDM_FILESAmS) . 

C0MMAM>_ID {1DM_F1LEEAVEAS )): 
SetHenuItemCoramandTD(myMenu. MEHTJ_ITEM(IDM^EXIT}. 

COMMAND_ID(IBM.EXIT)}: 

myHenu = GetMenuHandleCkEditMenuResID)j 
SetMenuItemConmiandID{iiiyHenu. HENI(_ITEM(I0M_EDITUND0). 

COMAND_rD(lDM_EDITTJM:0)) ; 

SetMer»uIt 0 iaCommandID[iiiyHenu. MEMU^ITEM{IDM_EDITOT]. 

GOMMAND,TD{rDM_EDITCUT)]: 

SetMenuIteiiiCoi!imflndID{iiLyMenu. MENU.ITEM [IDM_EDITCOPY) . 

COMMAtJD_tD{IDM_EI]ITCOPY}) ; 

SetMenuItedConHuandlD(myMenu. MENU_ITEM[IDM^EOITPASTE). 

COMMAND_TD(TDM_EDTTPASTE)): 

SetMenuItemGotmnandID (niyMeTiu. MENU_ITEM (IDM_EDITCLEAR) * 

COMMAND^ID{IDM_EDITCLEAR)): 
EetHenuIteraCoTiimandlD (myMenu. KENU„TTEM (I DM^ EDITS ELECT ALL) . 

GQHMAMD_rD (IDM_EDITSELECTALL)); 
SetMenuItemComMandID(myMenu* MEHU_ITEM(IDM_EDITSELECTNONE), 

COMMAND_rD(TDM_EOITSELECTNOKE)): 

ffendlf 


case kEventCommandUpdateStatusi 

myErr = GetEventParameter(tbeEvent, 

kEventParamDirectObject, typeHlCoramand. NULL, 
s i ae of (myCoamand). NULL. &inyCQtmiand): 
if ({myEri: = noErr) Siit 

((myCommand.attributes & kfllCommandFromMenu) t“ 0)) 
QTFrame_AdjustMenus(PtontWindowO* NULL* OL); 
b reak: 


We adjust the menus only if the command ID is being sent to us 
as the result of some event involving a menu (that is, if the 
kHICommandFromMenu bit is set in the command attributes). 


Handling Menu Selections 

When the user selects one of our application’s menu items, 
the Carbon Event Manager sends us an event of class 
kEventClassCommand and kind kEventCo mm and Process. Once 
again, we check that the command arises from a menu selection; 
then we call our existing function 
QTFrame_HandleMenuCommand‘ 


case kEv&ntConmiandProcess: 

myErr = GetEventParameter(theEvent, 

kEventParamDirectOhject. typeHICDmmand. NULL. 
si2eof( my Command). NULL. SmyCoitimand]: 
if {(myErr ^ noErr) && 

((myCoTiMiand .ettributea & ktnCoimnaridFroiiiHenu) !” 0)) 
myErr = QTFrame_HaridieMenuCoinmand (inyConmiand - coimnandlD) ? 

noErr : sventNotHandledErr; 


break; 


Of course, applications built on lop of QTShell may have 
additional menus, and we need to define command IDs for items 
in those menus are well. Listing 6 .shows how we can set up 
command IDs for items in the Test menu. 


Listing 6: Defining the application-specific comoiand IDs 

QTAppJnil 

/jfif USE_CAFBON_EVENTS 

MenuRef niyMenu = NULL; 


myHenu === GetMenuHandleikTestMenuReslD) ; 
SetMenuItemCommandlD(myHenu. HENU^ITEM(IDH_CONTROLLER). 

COMMAND„ID(IDM_CONTROLLER)): 

SetMenulteifiComniand ID (myMenu. HEMtI_ITEM(lDM_SPEAKER_EIJTrON) , 
COMMAND_ID(inM_SPEAEER_BUTTON)); 

fiiendif 


It's worth noting that we could instead embed command 
IDs in our application's resources. The xmnu’ resource type 
contains extended menu information, induding a command ID 
to be associated with a particular menu item. In QTSlicll, well 
use SetMenuttemCommandlD, as shown above. (It's also worth 
noting that we could specify command Ills in a .nib file, if we 
were using .nib files instead of resources to define (uir 
application's user interface.) 

Adjusting Menus 

Our application receives an event of class 
kEventClassCommand and kind kEvanlCommandUpdateStatus 
when the menus need to be adjusted. We can handle that 
event by calling our function QTFrame^AdjustMenus: 


Remember that an event handier should return 
eventNotHandledErr when we want the event to l>e propagated to 
other handlers in tlie call chain. Lve reworked 
QT Fra me_Handle Menu Comm and (and the menu handlers it calls) 
so that it returns a BtK)lean value indicating whether the menu 
command was handled by tlie application. We return noErr if we 
handle the event. 

Listing 7 shows our complete applieatitm event handler 
QTFrame_CarbonEventAppHandler^ which liandles ecimmand events. 


Listing 7: Handling commands 

QTFranieJ ^jirhonEventAppl landJcr 
PASCAL_RTN OSStatus QTFraine_CarbonEventAppHandlet 

(EventHandlerCailRef theCallRef, EventRef theEvent, 
void *theRofGon) 

I 

^pragma iiTmsed(i:beCaURef. theRefCon) 

UIiit32 myClasa. myKlnd: 

HICommand my Comma nd; 

OSStatue myErr ^ eventNotHandlEdErr; 

myCJass = GotEventClasstthEEvent): 
myKlTid = GetEventKind (theEvent): 

switch (myClass) I 

case kEventClassCominand: 
switch (myKlnd) ( 

case kEventCoitimandProcess; 

myErr = GetEventParameter(theEvent. 

kEventParaJiiDlrectObject» typeHIConmiand. NULL, 
sizeof (myConmiand) I NULL, inryConmatid) ; 
if ((myErr = noErr) && 

({myCommand,attributes & kHIGoimnandFramMenu) !” 0)) 
myErr = 

QTFrame^HandleMenuCommand(myCommand.c oramandID) 

? noErr : eventNotHandledErr: 
break; 
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case kEventCommandQpdateStatus: 

myEri: “ GetEventParameter (tEeEvent. 

kEventParamUirectObject, typcHICommand. HULL, 
sizeofCmyCommand). HULL. SmyCoramand]: 
if ((myErr = noErr) && 

((myCommand.attributes & kHlConimaiidFromMenu) f= 0)) 
QTFrame_AdjustMenuBCFrontWlndow{), NULL. OL); 
break: 

1 

break; 

case kEvent C1 a s sMenij: 

switch (myKlrid) [ 

case kEventMenuBeginTracking: 
gMenuIsTracking ^ true: 
break: 

case kEven tMenuEnd Tracking: 
gMenuIsTracking “ false: 
break: 

I 

break; 

1 

return(myErr): 

1 


As you can see, Eoward the end of 
QTFrame^CarbonEventAppHandler we also handle two 
comraands in the kEventCl ass Menu event dass; these commands 
are sent to our handler when the user begins and ends tracking 
a menu. In effect, the gMenulsTracking global variable indicates 
whether a menu is currently being displayed. We’ll use that 
global variable a bit later, when we see lio%v to task our 
QuickTime movies. 


specified window (or at any window in front of it) are processed 
by the Carbon Event Manager. The application remains in a 
modal stare until it calls QuitAppModalLoopForWindow. 



A QuickTime movie player. 


Wrinen by the QuickTime Team 
©2002 Apple Computer, inc. 




Figure 1: The Ahtnft ixjx of QWjell 


Handling Events for the About Box 

Our Alinut box is pretty .simple. Well install the standard 
window event handler for it, to obtain all the usual window 
behaviors: 

TiiyWindow = GetDialogWindow(myOlalog): 

InetallStandardEventHand]er(GetWIndowKventTa rget(nyWindow)); 


Installing the Application Event Handler 

Of course, we still need to install our application event 
handler, by calling InstallEventHandler. The Carbon Event 
Manager automatically insuills a standard application event 
handler, so we don’t need to do that, listing 8 shows the code 
w'e add to QTFrame_ I nit Mac Environment to install t^ir application 
event handler. 


Listing 8: Installing an application event handier 

QTrninit*_IniiMacEnvironmeni 

EventTypeSpec myEventSpec[] = \ 

IkEventClassMenu. kEventMenuBeginTracklng], 

! kEventCiassMenu, kE vent Hen uEndTrackIngli. 

[kEventClassCommand» kEventCommandProcess 1. 
t kEventCiassCommand. kEvenTCommandUpdateStatus J 

1 : 


gAppEventHandlerUPP = NewEventHandlerUPP( 
QTFrame_CarbonEventAppHandler); 
if (gAppEventHandlerUPP NULL) 

ItifitallEventHandier(GetApplicationEventTarget[), 

gAppEventHandlerUPP, GetEventTypeCount[myEventSpec], 
myEven t S pe c. HULL, NULL): 


Modal Windows 

Now ils time to wean ourselves of ModafDiafog. Happily, 
our application calls it only once, when we di.splay our About 
box (Figure 1). The Carbon Event Manager provides the 
function RunAppModalLoopForWindow, which we can use instead 
of ModalDialog to put our application into a modal state. When 
the application is in a modal state, only events targeted at a 


*fhe only thing tJur application needs to handle explicitly is a 
user click on the OK button or a keyboard shortcut for a click 
on that button. We can call SetWindowDefaultButton to map 
key!)oard events to the OK button: 

Ger:Dialogltem(ruyDialog. kStdOkltemlndex. SmyltemEind. 

^mylteiiiHandle. ^niyltetiiitect) ' 

If (myltemHandle NULL) 

SetWindowDefaultButton(myWindow. 

tControlUandle) mylteniHandle): 


And we handle user clicks on the OK f)utton by installing an 
event handler that processes events of class kEventClassControl 
and kind kEventControlHit. Listing 9 sIkjws the main segment of 
QTFranne_ShowAboutBox. Notice that we also register to receive 
draw events for the dialog window. 


Listing 9: Displaying the application's About box 

QTI’niiDe_ShowAboutBox 

/(if USE_CAEBON^EVENTS 

EventTypeSpec myEventSpec[] “ I 

[kEventClassWindow. kEventWindowDrawGontant), 

]kEventClassControl, kEventControlHit J 

): 


// instJiil a window handler for the dialog window 
GetDlalogItefli(myDialog, kStdOkltemlndex, StmyTteraKind, 
^myltemHandle, SimyltemRect): 

If (myltemEandle J* HULL) 

SetWindowDefaultButton(myWindow, 

(Gont rolHa nd1 a)rayItemHandle): 

InstallStandardEventHandler{GetWlndowEventTarget(rayWindow)}; 
if (gWlnEventModalHandlerUPP I= NULL) 

InstellEventHandler{GetWindovEventTarget(myWlndow)* 
gWinEventModalHandlertiPP ♦ 
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gWinEventModalHandlerUPP. 

GetEventTypeCount [utyEventSpec) . tnyEvEntSpec . 
(void MmyDialog, NULL): 

// display and handle events in the dialog box until the user dicks OK 
RunAppModalLoopForWindowCniyWindow): 
tfelae 

// display and handk events in the dialog box trntil the user clicks OK 
do j 

HodalDialDg(BModalFilterUPP, ^Byltem): 

I while (myltem != kStdOkltemlndex}; 

#endif 


We specify the dialog pointer of the About box as the 
reference constant when we cal! installEventHandler. This allows 
us to know which dialog liox to draw when we get the 
kEventWindawOrawContent event. Listing 10 shows our definition 
of our modal dialog event handler, 
QTFrame.CaitonEventIVkxIafWindowHandler. 

Listing 10: Handling events for the About box 

QTFra mc^ Ca r Ixm Ih cn i Modal VO ndowHandler 

PASCAL_ETN OSStatus QTFran5e_CarborLEveTitKodalWindowHandler 

(EventHandlecCailRaf theCallRef, EventRef theEvent. 
void 'theRefConJ 

[ 

tfpragm unused (theCallRef) 

UInt32 myClass* tnyKlnd: 

DialogPtr layUialog = (DlalogPtr)theRefCon; 

OSStatus myErr " eventNotHandledEtr: 

myClass = GetEventClaBS(theEvont); 
ntyKlnd - GetEventKind{theEvent) ; 

Bwitch (myClasa) I 

case kEventClaasWindow: 
switch (myKind] I 

case kEventWindowDrawGontent; 
if (rayDialog I- NULL) 

DrawDialogtaiyDiaiog) : 
myErc = noErr: 
break; 

\ 

break; 

case kEventClassContro.h 
switch (myKind) I 

case kEventControlHit: 
if (myDialog 1= NULL) 

myErr - QuitAppNodalLoopForWindowt 

GetDialogWii]dDw(niyDialQg) J : 

break: 

I 

break: 

I 

return(myErr): 


We call QuitAppModalLoopForWindow, and hence leave the modal 
suite, when the user clicks the OK bulton. 

Handling IVon-Documeiit Windows 

Let's digress briefly to fix a hug that can arise when QTShel! 
or one of its descendants is running on Mac OS X and we 
display a lielp tag. A help rag \s a message tliat can appear when 
the cursor is left morionless over some interface element 
(typically a wandow, a control, or a menu item) for a preset 
amount of time. Figure 2 shows a help tag associated with our 
Alx)ut box. 


Aboui QTShell 


A QuickTime movie player. 


tiJFrin-An Ku rfio nILTinr^gi Team 

Kick!am, the QuickTi me pe nguin? i ^ . 

m i ■wwn .i i rm A i ' I im p n- ■ -t niL. 



^ ott I 


Figure 2: A help tag 

li\s fairly simple to add lielp tags to a Carbon application. 
Listing 11 shows some code wc can add to 
QTFrame_ShowAboutBox to display the help tag illustrated in 
Figure 2. (The application's resources include two strings wnth 
the specified STR# resource ID and indices.) 


Listing 11: Adding a help tag to the About box 

(^ITni me_ShowAboutDox 


NMHelpContentRec myConteni:; 


myContent.version = kHeeHelpVerslon; 
myContent.tagSide = kHNAbsoluteCenterAligned: 

iny Con t ent, con renT [OJ , con tent Type ' kHNStringResContent: 
myContent.content|0]-u 4 tagStrlngRea.hramResID ^ 128: 
tnyContent .content jo] , u.tagStrlngRes. hmmindex = 1: 

myContent.content[ij .contentType “ kUMStringResContent: 
itiyContent .content f 1] .u.tagStringRea .hititiResID ^ 128: 
myContsnt.contentjl|.u.tagStringRea.hmfflTndex = 2; 

MacSetSect [fiiiiiyContent.absHotRect, 0, 0. 0. 0): 

HMSetWindowHelpContent (itiyWindow, &myContent) : 


Tile problem arises because a help tag is drawn inside of a 
small yellow window (as the drop-shadow in Figure 2 indicates) 
and our existing code is unable to dislinguisli lliat whndow from 
our movie or image windows. Currently, we determine whether 
a window is an application window (ihai is, a movie or image 
window') by calling QTFrame IsAppWindow, defined in Listing 12. 


Listing 12; Finding application windows 

(^'1 Frame_l sAppWindow 

Boolean QTFratne_IsAppWindow [WlndowRefetence theWindow] 

[ 

If (theWindow “ NULL) 
return(fal£e); 

#if TARGET_OS_MAC 

return[GetWindovKind(theWindow) kApplicacionWlndowKind): 
#endlf 

#-{f TARGET_0S,W:N32 
return(true): 

//end if 


The trouble is that — lo and behold — help tag windows 
also have the window kind kAppIrcationWindowKind. So the 
Macintosh code in QTFrame_lsAppWindow will decide that help 
tag windows are application window^s; eventually our 
framework code w ill retrieve the Windows’s reference constant 
and later doubly dereference it to get the associated window 
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objtfct data. On Mac OS X, m^here the operating Jiysteni is rather 
strict about memory ac’cesses, we’II get an access fault. 

There are several ways to avoid thi.s problem. Perhaps tlie 
best solution is to rework QTFrame_lsAppWindow so that it 
winnows out help tag windows. We can do this by inspecting the 
mndow elms of the window^ passed in, as shown in Listing 13- 


Listing 13: Finding.appHcatlpja windows Ciwised) 

QlFnimt_IsApp Window 

Bgolean QTFrame_l£AppWindow (WindowReferetice theWindow) 

( 

#if TARGET_OS_MAC 

t)Int32 EnyClaafi = D: 

OSStattis myErr = noErr; 

if (theWindow “ NULL) 
return Cfalse): 

nyErr = GetWindowClasB(theWindow, ^myClasa): 

If [myErr t= noErr) 
returnCfalse): 
else 

return (myClass “= kDocumentWitidowClasa): 

#Gndif 

Hi TARGET_OS_^WIN32 

return(theWindow != NULL): 
fendif 
) 

Here we look at the window class (which we retrieve by calling 
GetWindowClass). Our movie and image windows have a window 
class of kDocumentWindowClass. while help tag windows liave a 
window class of kHeIpWindowClass. Problem solved. 

It's worth noting that this problem has nothing to do witli 
Carbon events; rather, it arises from the fact that (with our 
original ccxie) a help tag is considered to he an application 
window^ with a bona fide window object attached to it. It’s aLso 
worth noting that the problem can arise even if our application 
doesn't display its own help tags; on Mac OS X, the Open file 
dialog box will display a help tag if the cursor remains 
motionless for the appropriate amount of time over a file name 
that's too long to fit in a column. Compare Figures 3 and 4. 



Figure 3." We Open file dialog box with a tmncatedftle name 
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Figure 4: A heif) lag in ihe Open file dialog Itox 


Event Loop Timers 

Because our applications play QuickTime movies, we need 
lo call MClsPlayerEvent periodically to make sure that 
QuickTime has time to process events for any open movies. 
When using the classic event model, we rely on the fact that our 
application will receive a steady stream of null events; since our 
call to MClsPlayerEvent is contained inside of 
QTFrame_HandleEvent, MClsPlayerEvent will be called often 
enough to keep any open movies playing smoothly. 

rhe Carbon Event Manager does not issue null events. To 
ensure that an open QuickTime movie is tasked periodically, we 
can install an event loop timer. We create a universal procedure 
pointer to our timer callback routine by calling 
NewEventLoopTimerUPP; 

gWinTtraerHandlerUFP ^ NewEventLoopTimerUPP{ 

QTFrame_CarbonEventWtndowTim 0 C)i 

Then w^e create a new timer and attach it to a window by calling 

I nstallEventLoopTimer; 

if (gWinTlmerHandlerUPP 1^ NULL] 

InstallEventloapTimer(GetHainEventLoop0, 0. 

TickeToEventTime (kVfNEMiniintjrEiSlEep) . 
gWlnTimerHandierUPP^ myWindowObJect. 

&{ ‘'niyWindowObjact) .fTimerRef) ; 

The first parameter specifies the event loop we want to 
attach the timer to; in QTShell w^e have only one event loop, 
which we get by calling GetMainEveniLoop. The third parameter 
indicates the desired peri(jd between timer calls. Tlie fifth 
parameter i.s a reference constant that's passed to tlie timer 
callback when it is executed; here we pass tiie window object 
a.ssociated with the window, so that we can use the window- 
specific data contained in it. An etmil loop timer reference is 
returned in the last parameter, which here is 
&(**myWindowObject).mmerRef. We need to keep track of this 
reference so tliat we can later remove die event loop timer w'hen 
the window is closed: 

If ((**myWiadowObjeer).fTlmerRef != NULL) 

RemovEEventLoopTimei: ((* 'tnyWlndowObject) /fTimerEef) ; 


As you can see, we've added a field fTmerRef to the window 
object record to hold the even! loop timer reference. 

We'll use our event loop timer callback function, 
QTFrame_CarbonEventWindowTimer, to call MCldle on the 
window's movie controller, as you can see in Listing 14. 

listing.H^Haiidliiiigevent loop ti mer c allbaclcs_ 

QTTrjme^Cajl^fonEveniWindow'nmer 
PASCAL_RTN void QTF r aflLe_Ca rbonE vent Wind owTi me r 

{EventLoopTiraerRef theTimer, void *theRefCoa) 

r 

^^ptagma unused {theTiJner) 

WindoirfObject myWindowObJect = (WindowObject)theRefCon; 

// just pretend a null event has been received.... 
if [(myWindowObject 1= NULL] fiii 

((**!iiyWindowObject} .f Controller 1= NULL)) 

If ([gMenuIsTracking || gRunningUnderX) 

MCldle((* ^rnyWlndowObjeet).fController); 

I 

We don't call MCldle if die menu is being tracked and weVe 
running on Mac OS 8 or 9. This is to prevent QuickTime from 
drawing on top of the dropped-down menus. 

Notice tliat we install a separate event loop timer for each 
open movie window. As an alternative, we could install a single 
application-wide event loop timer whose callback function loops 
through all open movie windows and calls MCldle on each 
windtjw’s movie conirtiller. This alternate strategy would require 
a small amount of extra code (principally to make sure we don't 
have an active timer if no movie windows are open), but might 
result in better efficiency (since we are using only one event 
loop timer). I'm told, however, that any efficiency gains are 
likely to be minimal; as a re.sult, I've chosen lo use one event 
loop timer per movie window, 

Tasking Interval Management 
We use an event loop timer to call MCldle, to task an open 
movie. This works great, except that the timer fires a! the 
specified interv^al even if none ol' the movie's data handlers or 
media handlers has any work to do. QuickTime 6 provides 
several new' functions that we can use to manage these tasking 
intervals. The key new function is QTGetTimeUntilNextTask, 
which we c'an use to find out when we next need to call 
MClsPlayerEvent or MCldle. For instance; 

QTGetTlmeUntilNextTaEktfiimyDuratlon, 60][ 

QTGetTimeUntilNextTask returns, in the first parameter, the 
length of time until a QuickTime movie needs to be tasked 
next, The second parameter indicates the de.sired timescale of 
that duration. Passing 60 means that we want 
QTGetTimeUntilNextTask to give us a duration in ticks. Passing 
lOOO would give us a duration in milliseconds. 

Adjusting the Classic Event Ijoop Interval 

We can use QTGetTimeUntilNextTask to adjust the interval we 
pas.s to WaitNextEvent in our classic event loop. Listing 15 shows our 
final version of QTFrame_MainEventLoop, 
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listing 15: Rctrieyiiig and dfe pa tching events (final) 

QTFramOlamJiventLoop 

static void QTFraroe_HainEvenrLoop (void) 

f 

#if USE_CARBON_EVENTS 

RunApplicationEventLoopO : 

^/else 

Event Record ntyE ve n t: 

long loyDuratioTi = kWNEMininitimSleep: 

while t S gShuttingCo-wn} I 
#if USE_TASK_HGHT 

// g^t the number of ticks until QuickTune's next task 
QTGetTimeUntilNextTaskf&inyDuratiQn. 60): 

if (myDuration = 0) 

myDuration = kWNEMiniinLunSleep; 
tfendif 

// get the next event in the queue 

WaitNextEvent(everyEvent* SirayEvent, myDuration* NULL) : 

// handle the event 

QTFramGjandleEvent C&myEvent ] ■ 

I // while ([gShuttingDown) 

#endif 

[ 

QTGetTimeUntilNextTask cun return a duration of D. which 
means that QuickTime wants to be called immediately. Itls 
generally a bad idea lo pass a sleep time of 0 to WaitNextEvenl, 
so we enforce a minimum sleep of kWNEMinimumSIeep ticks. 
(kWNEMinimumSIeep is set to 1.) 

Adjusting the Carbon Event Loop Timer Interval 

We can also use QTGetTimeUntilNextTask to adjust the 
period of our event loop timer. Each Lime t)ur timer callback 
function is called, we can determine the interval to the next time 
we need lo call MCldle and then reset the timer intetval 
accordingly. Here, we want to wotk in milliseconds: 

QTGetTiraeUtitilNextTask(iimyDutatiort* 1000): 
if (theTimer !“ NULL) 

S e tE ve-ut Loo pTlmer NextFl r eTime (th eTijiie r» 

myDuration * kEventOuxatlonMillisecond )i 

Listing 16 .shows our event loop timer with the tasking 
management code in place. 


listing 16: Handling event loop timer callbacks (revised) 

Q'iTr;imc_C]:iii>(}ii£vcniVt1iiduwTimtT 
PASCAL_RTN void QTFtaHie^CarboriEventWlndowTinier 

(EventLoopTlmerRef theTitner, void ‘theRefCon) 

I 

WindowObjcct myWlndowObject = (WlndowObject)theRefCoii: 

Hi USE_TASK_KGHT 

long tnyDu ration = OL: 

// get Uic mimlHT of millbcLonds luitil QuickTime s next task 
QTGetTimeUntilNextTask(^myDuration. 1000): 

if (myDuration = 01 

myDuration = kHinAppTanklnMlllisecaj 

// set ihc timer Ui fire at thai time 
If (theTinier E“ NULL) 

Se t Ev en t L 0 opTime rNext F i reTime (t h eTime r, 

myDuration * kEventDuratlonMillisecond); 

//end if 

// gist pretend a null event has been received..,, 
if ((myWindovObJect 1= NULL) 


{(**n]yWindowObject) .fController E= NULL)) 
if (fgMenuIsTracking || gRunningUuderX) 

MCIdle[{*'mjWindowObject).fController): 
i 

If QTGetTimeUntilNextTask returns the value 0* well once 
again peg the delay to a predefined minimum to avoid 
swamping the processor with our QuickTime tasks, 

HandUog Task-Sooner Notifications 

What happens if QuickTime needs to be tasked before the 
event loop timer fires next? To handle that possibility, we can 
install a task-sooner callback function. QuickTime calls this 
fiinction if our application needs to task one of its movies 
before a specified event loop tinier is scheduled to fire. We call 
QTInstallNextTaskNeededSoonerCallback to install our callback 
fmetion: 

//if USE_TASK_MGNT 

gQTTaekSocmerUPP = NewQTNextTaBkNe&dedSoonerCallhackDFF 
(QTFranie_NextTaskNeededSooiierProcedure): 
if ((gQTTaskSoPnerUPP E- NULL) 66 

(gAppEveuuLoopTimerRef 1* NULL)) 
QTInstallNextTaskNeededSoonerCallbacktgQTTaskSoonerUPP, 

1000, 0, (void *)(■‘myWindowObjeetJ .fTimerRef); 

-tfendif 

The calll>ack Function is ciuite simple. It calls 
SetEventLoopTimerNextFIreTime to reset the event loop timer 
(Listing 17). 

Listing 17: Handling task sooner notiHcatioiis_ 

QTFmmc„NLxlT:iskNLcdt:dSiX>ncrPnK:cduiC 
PASCAL_RTN void QTFraEie_NextTaskNeededSaonerProcefiure 

(TimoValue thoDuration* unsigned long theFlags, 
void “theRefCon) 

t 

//pragma unused (theFlags) 

EventLoopTimerRef myTimer = (EventLoopTimerRef)theRefCon: 

if (myTimer J= NULL) 

SetEYentLoopTlnierNextFireTime (myTimer. 

theDuratlou * kEvetitDuratlonMilliaecond): 

I 

Of course, when our application is quitting, we want to 

dispo.se of the callback fund ion LIPP: 
if (gQTTaskSoonerUPP 1= NULL] 

DiB p oa eQTNext Tas kNee d ed S o one r Ca11b a e kUPP(gQTTaBkS ooue r UP P); 


The Carbon Movie Control 

Nowl wouldn't it be great if tJtere were a way to display a 
movie in a window’ wad tout having to worry’ abt^ui all this tasking 
and timer interval rescuing and event handling? Thai is precisely 
what is provided by the Catix}n mome corUivi^ introduced in 
QuickTime 6 on Mac OS X. Tlie CaHion movie control is a custom 
control dial displays and manages a QuickTime movie. We create 
the control by calling CreateMovieContraf like Uiis: 

niyErr = CreateMovleControl(theWindow* imyRect, theNovie, 
myFiags, IdnyControl): 


The first parameter is the window that is to contain the new^ 
control. The second parameter is the control rectangle (in local 
coordinates); in our case, we’ll use the entire movie window. The 
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thirti parameter is the movie to be displayed using tfie movie 
control, a handle to which is returned in the fifth parameter. 

Tlie fourtJi parameter to CreateMovieControl specifies a set of 
Hags tliat modify the !:>ehavior of the new movie control. 
Currently these flags are defined: 

enum \ 

kMovi^CotitralOptionHideCdtitroller = (IL <<! D) * 
kHovleControlOptlonLocateTcipLeft ^ [IL << I) * 

kHovieControlOpxionEnableEditing ^ (IL << 2)* 

kMovieConttolOptionHandlEEdltingHI “ [IL << 3)* 

kMovieControlOptionSEtKeysEnabled = (IL « k], 
kMovieControlOptionManuallyldled ^ (iL « 5) 

I : 

In QTShelf we ll use the.se flags: 

myFlags = kMovieControlOptionSetKeysEnabled | 

kKovleContircilOptionLocateTopLeft | 
kHovleControlOptionEnahleEditing: 

The kMovieCofitrolOptionManuallyIdled flag indicates that we want 
to task the movie ourselves (presumably with our owm event 
loop timer). If this flag is clear, the movie control uses its own 
event loop timer to task the movie. 

The movie control created by CreateMovieControl is 
associated with a movie controller; this movie controller is 
always attached to the movie and will be initially visible unless 
we set the kMovieControlOptionHideController flag. If we want to 
call movie controller functions, w^e can retrieve the movie 
controller by calling GetControlData: 

myErr - GetControlData(myControl, kControlEntireControl, 
kMovieControlDataMavieController, aizeof (inyHC}. 

(void *)^tnyMC. HULL): 

To appreciate just how cool the Carbon movie control is, 
try this: take some sample code that uses the Carbon event 
model but which know^s nothing about QuickTime. Add the 
few lines of code you need to open a movie file and create 
a movie from that file. Add the line of code above that uses 
CreateMovieControl in the appropriate spot. Add the 
necessary QuickTime libraries to your project. Compile and 
link. Voila, you now have a QuickTime-savvy application. It 
can't get any easier than that. (But it can get better: the 
Carix^n movie control supports the basic movie controller 
editing operaiions, and it also adjusts the Edit menu items as 
appropriaie to the state of the movie if the 
kMovioControlOptionHandleEditingHI flag is set.) 

Conclusion 

Lels wrap things up. We’ve managed to bring QTShell into the 
2]^^ Century by replacing its “classic'* Event Manager underpinnings 
with the more elegant and more efficient machinery of the Carlson 
Event Manager. To accomplish this, we WTOte and installed a few 
event handlers and a tinier callback function, and w^e set the w'hole 
thing in motion by calling RunApplicationEventLoop. The Carlion 
Event Manager then sends our application events as tliey become 
available, and it invokes our timer callback function periodically so 
that we can call MCldle to task our open movies. 

We also saw' how to use the tasking inrerv^al management 
functions introduced in QuickTime 6 to adjust the inteml 


between timer callbacks. It's important to understand that w'e 
need to use these lunetions only in Carbon event-savvy 
applications that install their own timer callback functions or 
in any Macinttish applications that use the “classic" event 
model. On Windows, or in Cocoa application.s that use the 
NSMovie and NSMovieView classes {which we ll investigate in 
an upcoming article), the tasking intervals are managed 
internally. Also, if we use the Carbon movie control (available 
on Mac OS X in QuickTime 6 and later), we don’t need to 
worry about handling events or timer intervals at all. 

QTShell .still contains a few' loose ends, In theory, there is 
no need for our About box to be a modal window'. It could just 
as easily be implemented as a document w'indow with a special 
w'indow class. This w'ould allow us to keep the About box open 
w'hile the user operates on an open movie window. Til leave this 
as an exercise for the interested reader. 
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Sound Studio 2.0 


Built for Mac OS X 

With Sound Studio 2.0, you can: 

Digitize cassette tapes and vinyl records to make CDs 
Record live performances and interviews 
Record your favorite radio programs with Timer Recording 
Edit out dead air, glitches, and mistakes in recording 
Apply any of 19 effects including Reverb and Chorus 
Create new sounds and toops 

Sound Studio ia an audio recording and editing application built for 
Mac OS X. It can also run on Mac OS versions 8.1 and up. Some 
systems may need a USB audio input device to record. 

Only $49.99 
Download 14-day trial version at 

http://www.felttip.coni/ss/ 

felt tip software 

807 Keely Place, Philadelphia, PA 19128, USA 
wwwT^lttlpxom 
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MAC OS X 


£iV Andrew Stone 


Doctor - Wrapping UNK CU’s into GUIs. 


With OS X conies a wealth of UNIX command line 
programs to accomplish all sorts of tasks, Wrapping these 
Cirs into a graphical user interface that Mac users expect 
and even demand can quickly turn this fortune into usable 
programs. This month Til provide the complete source to the 
graphical user interface and CLI glue for "‘DOCtor’' - an 
application to convert Microsoft Word .doc documents into 
Mac OS X viewable PDF. Although this program calls the 
UNIX executable ’‘antiword", it provides a framework 
skeleton which could be used on any executable. You will 
learn how to: 

• modify UNIX programs to work in a GUI 

• launch and log the output of a UNIX program 

• accept drag and drops on a w indow 

• communicate with another program via its API 

• extend NSFilemanager via categories 

• open URLs programmatically 

Pull source code to both DOCtor and aniiword is available 
at our web site at: http://www.5tone.corn/DOCtor/DOCtortar.gz. 

Is There a DOCtor in the House? 

Proprietary file formats are annoying and almost useless 
to the ever-growhng number of people who refuse to use this 
class of software. The GNLf (GNU means “GNU Not UNIX", 
recursively) community is a diverse, global collection of 
forward thinking programmers w'ho produce code that is 
protected under the GNU Foundation's “Copyleft". Instead of 
taking away the user's rights, it guarantees that others can 
copy and use the code, as long they continue to give it aw'ay 
complete and free. 

When the PStilU^ engine author, Frank Siegeri, informed 
me of the antiword project, I thought it would be useful to 
add a GUI and more functionality to this UNIX program. 
Antiword converts Word documents into PostScript. While PS 
can be printed, it cannot be view'ed directly under Mac OS X, 
Doctor calls PStilFs published application programmer’s 


interface (API) to distill the PS into PDF. It then passes the 
PDF to another program for display. If Stone Design's 
Create® is installed, DOCior will show' the file in Create; 
otherwise, it will use the user's default PDF viewer (Preview, 
for example). 

Call the Doctor! 

The design of a GUI for a llNIX executable us really a 
task of mapping the possible parameters of the command line 
program to user interface elements. Here's the output from 
running antiword from the command line without any 
parameters: 

[ibislAutiWorii/aOCtor/antiword 1 andrewX ./antiwtjrd 
Name: antiword 

Purpose: Display MS-Word files 
Author: (C) 1993-2001 Adri van Os 
Version: 0,32 [05 Oct 2001) 

Status: GNU General Public License 
Usage: antiword [switches] wordfilel [wordfile2 
Switches: [-t|-p papersi^e] [-m mapping,] [-w #] [-i #] [-X #] [- 
Ls] 

-t text output (default) 

-p <paper name> PostScript output 

like: a4, letter or legal 
-m ^mapping) character mapping file 
-w <width> in characters of text output 
-i <level> image level [PostScript only) 

-X <en(!oding> chatacter set (Postscript only) 

-L use landscape mode (PostScript only) 

-s Show hidden (by Word) text 

First, decide which parameters are relevant. We’re not 
interested in the parameters that apply to a simple text 
translation of the document; we w^ant the flags for PostScript 
output. Second, decide which parameters the program should 
suppon. We will let the user specify the paper type t -p) and 
orientation (-L), but leave image level (-i) and character set (-X) 
for future enhancements. Third, decide how to display the 
options, I often choose to simplify the interface by hiding expert 
options in drawers. This way, the “easy” interface is simple and 
clean, but experts have the options at their fingertips: 


Andrew Stone <andrew@stone.com> is founder of Stone Design Corp <http;//ww^^stonexom/> and divides his time between Farming on the earth 
and in cyperspace. 
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Awesome! 


"The power, quality and feature set of 
Lasso Professional 5 is very impressive. 
The new documentation is definitely 
among the best in the business/’ 

Johan 5d/ve; Ha/mstad, Skveden 


"Blue World has managed to add an 
immense amount of functionality and 
scalability without sacrificing any of the 
ease-of-use of previous versions. New 
features like LassoApps, custom tags 
and LassoScrlpt cnaate a development 
environment that seems almost limitless." 

Tom W^'ebe; I'ancouver, Canada 



Lasso' 

ProfessioiialS 


Oukkiy Powers 

Dat»t3rrrtnlAtebAppl(£Jtions 



"With Lasso, \ have been able to single- 
handedly develop sophisticated solutions 
for internal and external use in less time 
than I see teams of people take with 
other middleware languages." 

Greg WiHsts; Santa Ana, Ca/ffornia 


"This new release, I have got to admit, 
is truly amazing. The rich array of new 
features, the brand new documentation 
and the amazing new administration 
interface make Lasso Professional 5 
definitely worthy of a purchase.” 

Brian Oisen; Brooklyn, New York 


Upgrade today to the most powerful Web application server for 
Macintosh and beyond and you'll discover why so many Web 
developers claim Lasso Professional 5 is the must-have tool for 
quickly building and serving powerful data-driven Web sites. 

Lasso Professional 5 introduces a next-generation, object-oriented 
Web programming language, advanced Web application server 
administration, an embedded Lasso MySQL™ high-performance 
database server, a new distributed architecture, new platform and 
data source support, unprecedented extensibility and customiza¬ 
tion, 1800 pages of rewritten documentation and over 200 new 
features and enhancements. Lasso Professional 5 provides vast new 
power and features while maintaining the legendary ease-of-use, 
performance, and reliability that make Lasso the preferred tool for 
tens of thousands of Web developers, ISPs, and IT/IS professionals. 

If you're serious about building and serving data-driven Web sites, 
but don't want to spend a serious amount of time getting it all to 
work, there's no better choice than Lasso Professional 5. 

Visit the Blue World Web site today and see how Lasso products can 
help you quickly build and serve powerful data-driven Web sites. 

Lasso - The Leading Web Tools for Macintosh and Beyond 



Lasso Administration controts your entire setup via an 
attractive and intuitive Web browser interface. 





Lasso Database Browser provides instant access to all 
your databases, without writing a line of code. 


blueworld 

WWW* bl u e worl d .com 


& 2001 Slue World C4>m?nurijEBtions, Inc. MySOt is a tradEtnajk of AB. FiTeMaJcec Pro is b nEgistorEd tradBrridrfc of F[]EMak«'. Iric. Lasso. Lasso Prof^sianat LassoApp. LassoScfipt 

and BIm World afe of Qliw World Cortimijoicstjorkt, loc. /Ul nsiorvEd. 























^ DOClOr Edi! Tools TexiExiru Windcm 



The ^mcl Doctor's interface is simple — 
hut exfmes more options for the exjmi in the dramr 


The CiASSES and Their Responsibiijties 

TIil* Doctor is conipo.stjd of 3 “brain” classes^ 2 user 
interface subclasses, and 2 category extensions. The basic design 
is a central controller lhal ccjordinates the user interface with the 
antiword process. 


Impact your bottom line while working with 
dedicated proponents of Apple technologies 


With us^ your only constant is success. Our custom solutions help our 
clients excel their business objectives and effectively target their 
audience* That's why we suggest that we run your technology while 
you play the winning shot* 


Core Competencies ^ 

WebObjects development 

Mac OS X application development 

Cocoa application porting 

Carbon porting 

Mac OS product maintenance 

Windows/Mac OS/Untx porting 

Cross-platform development 

Service Offerings 

Offshore Project Development 
On-Site Staff Augmentation 
Off“Site Project Development 
User Training 



For More Information 

visit http://www*avestacs,com 
Email: mithu@avestacsxom 



Avesta Computer Services, Ltd* 
USA . EU . Asia 



The Brain Classes; DRControUer^ Conversioojob and 
SDLogTask 

The mapping between the user interface and anti word is 
handled by our NSApplication's delegate class, 
DRControUer. DKController is respon.sible for accepting 
input from the Ul, handling drag and drops, and providing 
feedback on the process to the user. It also manages what 
happens after anti word has successfully translated the *doc 
into PostScript, including calling the PStill^'^ API* 

Each translation job is represented by an instance of 
Conversior\Job - this neatly wraps up the options into the 
instance variables of this class* Conversionjob's 
responsibilities are to create an argument array and launch 
and monitor the antiword UNIX process. Conversionjob also 
determines what files can be translated - note the use of 
NSFileTypeForHFSTypeCode(‘WD[3N1 which allows WORD 
files without a “.doc” extension to he correctly identified as a 
WORD document. 

The SDLogTask is a reusable wrapper on NSTask that 
simplifies the calling of a CLI, as well as providing any output 
from the running of the program to the console window, if 
its visible. IPs a standard addition to many of the Stone 
applications. 

The User Interface Classes: EasyWtndow and 
DragFromWell 

The main conversion window is an instance of 
EasyWindaw - a .syhcla.ss of NSWindow that handles the drag 
and drop of .doc files. The rea.son we subcia.ss window is to 
get cursor change feedback whenever the user drags a 
relevant Ole over any part of the window', including the title 
bar. Instead of including program specific knowledge in this 
class, EasyWindow' asks the NSApp s delegate, DRController to 
both determine wTiich files are acceptable and what gets done 
when the file is dropped. I'his is a good strategy for reuse of 
111 components - concentraie the logic in the controller, and 
make the UI components as versatile as possible. 

When the file conversion is complete, an instance of 
DragFromWeU, an N.SI mage Well subclass, displays the 
output file’s icon. DragFromWeU also allow's you to copy the 
file to the desktop or other Finder location, as well as show 
you how to implement a ^Reveal In Finder”. Finally, it passes 
on “drags” to the w indow , so that all drag and drop code is 
centralized. The DragFromWeU is also a standard Stone 
component. 

Category Helpers 

Categories are additional or replacement methods on an 
existing Objective C class. This language feature lets you add 
power to Apple’s Frameworks, and are very suited to reuse. 
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NSFileManager(NSFile]Vianager_Exteasions) knows 
Jiow to create writable Folders, determine a suitable 
temporary folder, and hand out unique names based on a 
template, and is a standard addition to all of my applications. 

NSFileHandlefCFRNonBJockinglO), written by Bill 
Bumgarner, provides some fixes and additions to the 
Foundation class NSFileHandie. 

Making the Application Tile Accept Drags 

The simplest way to use DOCtor is to drag a file onto 
the Doctor’s application icon in the Dock or Finder By 
implementing one simple mediod in the NSApplication's 
delegate class, you add this functionaliiy: 

'(BOOL)application:[NSApplication *)sender 
openFile:(HSString *)path 
f 

return [self convErtAndOpenFile:path): 

[ 

There is one more thing you have to do - set up the 
acceptable document types in Project Builder’s Target 
inspector, Application Settings panel: 


II i» r? 4* f 


4 I l| Q 


^ ^ TwflBt: DQC mr s 


^ I ▼ Document Tvpefi 


Pmcwntm Tifp* ni^tiinruiliLfL 


n fmrf wDflN 


ICDn (iFe. wvdDw: 
D6tUlR<« CIjim 


pjtMw Up** 


inwpr POC «Pt iWit 


ftsTirtm 


■ ¥k4wr 


2 Plw 


SeUing tbe Document Types alerls Finder to whui sorts of 
documentsyott can open 


The Cool Stuff 

Modifying antiword 

I wanted to use the standard distribution of Adri van 
Os's antiword (hltp://www,winffeld.denion.nl/index.html), as 
poned to Mac OS X by Ronaldo Nascimento. There was a 
glitch how^even antiword expects its resource files to be in a 
certain location, which makes a simple installation difficult. 
I opted for minimal changes that wouldn’t affect the base 
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Cross-platform diagramming arid drawing tool 
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and maps easily. Use 2700 pre¬ 
drawn objects to quickly create 
documents, and export them to 
HTML or PowerPoint to present to 
your colleagues or clients. Works 
under Mac OS X, Classic Mac OS 
and Windows. 


Use ConccpiDrouu Pro for: 

• UML 

• Network Diagrams 

• Flowcharts 

• Web Site Schemes 

• Interface Modelling 
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distribution. By adding a _macosx define in the makefile and 
redefining GLOBAL_ANTIWORD_DIR to (the current 
directory) in antiword.h, we add support for having the 
resource files local to the executable, wherever the user 
installs the application. In conjunction with this change, we 
also need to set an environment variable $HOME w'hen 
calling antiw^ord from SDLogTask: 

[[SBLogTask alloc]inltAndLaunchWithArgs:[self arguments] 
executable:[antiward 

stringByAppeTidingPathComponent :@”antlwoE:d”] 
directory:antiword logToText:[[NSApp delegate] logText] 
lncludeStandardOutput:NO outFlle:outputPath owner:self 
environment![NSDictlonary 

dictlonaryWithObj ectsAndKeys:antiwotd, .nil]J: 

For the most part, standard Unix exeeutahies wall not 
require any code tweaking to be incorporated into your 
application. 

Remote methods 

Moving data between applications is pretty easy, and getting 
a quick connection to an application via low level much calls can 
avoid the ovei head of the extremely easy ro use NSConnection 
methiKi rootProxyPorCannectionWithRegisteredName:. See 
lookupPStillDOServetO for usage of bootstnip_kK)k_up() and 
connectionWithReceivePort:. Don’t forget to assign the f^roxy its 
“knowledge": 

// in order for a remote object to res|>ond to meih{xis, it needs to l>e told wliui it will 
respond tof 

[theProxy setProtocolForProKy:@protocolCPStillVended]1: 

Once you have this routProxy CDtinectloii with PStill, you can 
access the Objectlv© C methods of the PStillVended protocol 
in PStill. Par example to convert sn eps file to a pdf 
file* 

If [ [theProxy convertFileilnputFlle toPDEFileioutputFile 
d elet eXnput:NO]) 

// success! 


Tfien, to view the PDF, we first iiy^ the Stone Studio's Create 
- otherwise, we let NS Workspace figure out the user’s default 
application for viewing PDF: 

NSWorkspace *wm ^ [MSWorkspace shared Works pa ere] ; 

if ((I[NSUserDefaults standardUserDefaults] 
boolForKey rJ^'^DontOpealnCreate'*]) || t [wm openFile: pdf File 
withApplication:@''Create” andUeactivaterYESl) \ 
return [wm opeuFile:pdfFile]: 

I 

Also, note use of NSWorkspace's openURL: - this makes the 
kiunching of the user’s favonte browser to a given URL '"just work'': 

[[NSWorkspace sharedWorkspace] openURL:[NSURL 
URLWithString!@’'http!//ww¥*stane,com/’'l ] ; 


The Code 

amivord 0*32 diffs: 

diff r -C2 antiword.0,32/Wakefile.HacOSX antiword.0*32- 
gui/Hakefile.MacOSX 

antiword.O*32/Makefile.MacOSX Wed Oct 24 1S:3S:04 

2001 

antiword,0*12-gui/Hakefile,MadOSX Tue NdV 11 10:20:09 
2001 


*** 9,13 * * * * 

DB - MDEBUG 

// Optiraizatioii: -0<,n) or debugging: -g 
I OPT = -02 

LDLIBS 

— 9J3 — 

OB - MDEBUG 

# Optimlzatlaiii: - 0 <n> or debugging: g 
I OPT = -02 -0_^macoex 

LDLIBS 

diff -r -C2 antiword.0,32/antiword,h antiword.0.32- 
gui/antiword.h 

'** antiword.0,32/antiword,h Tue Sep 23 17:36:47 2001 

— antitford. 0.32 -gui/antiword.h Tue Nov 13 10 :IB :34 

2001 


REALbasic 
AppleScript 


Java 


C++ 


Director 


SQL 



Valentina 

Object-Relational SQL Database 


Revolution 

XCMD 

MetaCard 

I n 

SuperCard 

WebSiphon 

futureBASIC VisualBasic 


The fastest database engine 
for MacOSAVindows 


It operates lOO's and sometimes 
a 1000 times faster than other systems 

www.paradigmasoft.com 

Hosted by macservemet 

Download full featured evaluation version 
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143,146 
— 143^150 — 

^define ANTIWOKD^DIR 
iMefine ¥ONTNAMES_FILE 

+ ifelif defined (_macosx] 

+ //define GLOBAL. ANTI WORDJIR 
+ //define ANTIWOKD_CIR 
+ //define FONTNAMES.FILE 
//else 

//define GLOBAL^ANTIWORI]_I}IR 


"antiword" 
"fonTname.tx!" 


"antivard" 

■■fentnames'' 

" / opt / a n 11 wo r d / S b a r e " 


//////// llRf:ontmlkr,h /////// 

#lmpcitt <Cocoa/Cocoa*h> 

@lnterface DRController : NSObject 

I 

IBOutlet id statusField: 

TBOutlet id well; 

IBOutlet id window; 

lEOutlet id portraitLandscnpeMatrix; 

IBOutlet id paperSizeFopLJp: 

IBOutlet id openlnCreateSwitch: 

IB Out let id textLogView://tlie console 

IBOutlet id drawer; 

IBOutlet id tab View: // GPL license and other help info 

I 

// exposed API for drag and drops: 

- {BOCL)convertAndOpenFile:(NBString 'JdacFlle; 

// the callback after the antiword executable terminates: 

- (void)tasKTerralnated;tBOOL)success outputFile:(NSString 
*)outpout; 


U IB actions open MainMenunib in IB to see what's connectetl to what: 
// menu items: 

’ (iBActlon)gotoStoneSite:(id)sender; 

- (IBActlon)showLogAction:(id)sender: 

- (TBAct1 on)showGPLAction;(id)sende r■ 

- (IBAction)showSoureeAction:(id)sender; 

- [IBAction)showDOCtorSourceAction:(id)sender; 


// ui items: 

* (lEActlon)cbangeOpenlnCreateAction:(id)sender: 

- (IBAction)toggleBrawer;(id)sender; 

// our console text: 

- (idllogText; 

@end 


IlinUI DRController,m lUIUI 

//import <FoLLndation/Foundation,h> 
//import <AppKit/AppKit .h> 

//import <stdio,h> 

//import <itiach/iiiach.h> 

//import <servers/bootstrap,h> 
//include ^unistd.h) 

//import ■’DRControllet .h'* 

//import “ Con version Job. b" 

//import '’NSFileManager Extensions.h"* 
//import "DragFroinWell ,h” 



POWER TOOLS FOR YOUR WEBSITE 


Onix ’ Search and Retrieval Engine 
RoitteX - Document Filtering and Reliting Engine 
Brevity - Document Summarization Engine 


hftp://www.lextek.cain 
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// the first part of this file contains the routines needed to ask another Cocoa app 
// to do something. In this case, we ask PStiU to convert a PostScript file into PDE 

^define PStillFilterServer ([NSString \ 

s tringWithFomat: §^PS ti 1 iFllterServer - \ 

[[NSProcessInfo procsssinfoj hostName]]) 

©protocol PStillVendcd 

// 0 = succes anything else = Mure 

// caller's responsibility to make sure outpvitFile is wriieable and not 
// existing! 

' (Int)convGrtFlle:tNSString ')inputFlle 
toPDFFile:(NSStcing *)outputFile 
deletelnput:[BOOL)deletelnput i 

// you can also convert many files to one single PDF with this one: 

' (Int)convcrtFlI ge:(NSA rray *)fullPathEToFiles 
toPDFFlle;(NSString *)outputFile 
deletelnput:(BOOLjdeletelnput i 

// when licensing is done, this will return YES, otherwise NO 

- (BOODapplicationReadyForXnput: 

// for jobs to show a preview from a thread 

’ (void) showImageFile:(NSString *)file widths(int)width 
height:(int)height 

iaEPS:(BOOL)isEFS rotation:£Int)rotation 
pageNumbet:(int)pageNumber: 

©end 

/define USAGE NSLog(©"This Print Filter requires PStill for 
Mac OS X by Stone Design and Frank Siegert* Visit 
ww. St one .com to download and full information.") 

^define WAKE_UP_WAIT 5 

static IdCPStillVended) lookupPStlUDOServertvoid) 1 
port_t sendHachPort: 

NSDistantOhject *rootProxy = nil: 
id<PStlllVended> result: 

// First, try look up PStill ;s DO objea in liic hooisinip server. 

//This is whcTC the app registers it by default, 
if ((100TSTRAP_SUCCESS “ 
bootstrap_look_up(bootstrap_port. 

(char *)£ [PStillFilterServer cString]}. 
^sendMachPort)) && £POKT_miLL !" aendMachPoft)) I 
NSConnection *conn = iNSConnection 

connectionWithReceivePort: fNSPort port) 
sendPort: [NSMachPort 
portWithMachPo rt:sendMach Po rt] ] : 
rootProxy “ [conn rootProxy]: 

I 

// If the previous call failed, the following might succeed if the user 
// logged in is running Temiinal with the PublicDDStn. ices user default 
//set. 

If (IrootProxy) I 
rootProxy = [NSCo tin action 
rootProxyForConnectlonWithRegisteredName: 

PStlllFilterServer host:©""]: 

//We could also try to launch PStill at this pejim, using 
// the NS Workspace protocol. 

if [!rootProxy) [ 

if (I [[KSWorkspace shatedWorkspaceJ 
launchApplication:@”PStlll"j) f 
USAGE; 
return nil: 

I 


sleep [VAKE_nP_WAlT) ; 
rootProxy = [NSConnection 

rootProxyForConnectionWithRagisteredNanieiPStillFilterServer 
hosti©""]; 

I 

if CIrootProxy) I 

fprititf(stdetr."Can't connect to P3till\n"): 
return nil: 

I 

[rootProxy setPtotocolForProxy:©protocol(PStillVanded) ] : 
result = (id<PStillVended>)rootProxy; 
return result: 


BOOL convertFiles(NSArray ^inputFlles. NSString *outputFlle) 

I 

ld<PStillVended> theProxy = lookupPStillDOServer(): 

// if we can't find it, bail: 

if (theProxy ]= nil) [ 

// if she’s not launched, we wait until she’s licensed or they 
// give up on licensing: 

while (t[theProxy applicationReadyForlnputl) [ 

[NSThread sleepUntllDate:[NSDate 
dateWithTimelntefvalSinceNow:0.1]] : 

1 

if [([inputElles CQunt]=“l && [theFroxy 
convertFlle:[InputFiles objectAtIndex:0] toPDFFile:outputFile 
deletelnput:NO] “0)) f 
return YES: 

I else if ([theProxy convfirtFile5;inputFiles 
toPDFFile:outputFile 

deletelnput:N0l) I 

return YES: 

1 else I 

NELog [©"Couidn' t convert li®**, [inputFiles 
objectAtIndex:0]); 

1 

I 

else I 

NSLog[@"Couldn't connect to PStill"); 

I 

returii NO; 

I 

©inipleraentation DRController 


// Launching a URL in tlte user’s fivorite browser is this simple in Cocoa: 

* (IBAction)gotoStoneSltG:(id)sender I 

[[NSWorkspace sharedWorkspace] openURL:[NSURL 
URLWithString:@"http;//www,atone.com/"]] : 


’ (IBActlon)showDOCtorSourceActlon;(id)sender t 
[[NSWorkspace sharedWorkspace] openURL:[NSURL 
URLWithString:@"http://www.stone.com/DOCtor/"]]: 

1 

// when the Application launches, iict the slate of the inteiikce to match the user’s 
prefemnees: 

- (void)awakoFromNib ( 

[openInCreateSwitch setState; I [[NSUserOefaults 
standacdUserDefaults] boolForKey:©"DontOperiInCreate"]] : 
f 

' (IBActlon)changeOpenlnCreateAction:(id)sender: 

i 

[[NSUserDefaults standardUserDefaults] 
setBool:I [openInCreateSwitch state] 
fqrKey:©"DontOpenlnCreate"] : 

I 

* (IBActlon)shovGPLAction:(id)sender [ 
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FairGom offers this exceptional performance, unsurpassed data availability and rock solid reliability with a low total cost of ownership and flexible Licensing options. 

Get more for your development dolbr! Visit ww wJaircom.com/ep/freecdofrer today for a free developer ^s CD, 

FairCom Offices 

USA _ 573.445.6S33 

EUROPE _ +3j>,035.773.464 

JAPAN _ +SL59.229.75t>4 

BRAZIL +55.1L3872,9S02 


Mac Support Since 1SS5 * www.faircom.com • USA. BOO.S34,81iSO • info@faircom.com 
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// In Interface Builder^ you can set die identifier on each tab view 
// this allows you to progranimaticalfy^ Mcleci a given TMi: 

(tabView selectTabVlewIteniWlthldentlf ier :®"GPL”] : 

// [X>iit Ibrgct to order the window frr>nl in case jt’s hidden: 

([tabView window] makeKeyAndOrderFront:£elf] : 


- (void)revealInFinder; CNSStrlng *}path I 

IDOL isDlr; 

if ([ [NSFileManager defaultManager] fileExistsAtPath:path 
isDirectory:&isDlr]) [ 
if (isDir) 

1[NSWorkspace shatedWorkspacs] selectFilernil 
inFileViewerRootedAtPath:path]; 
else 

[ [NSWotkspace sbatedWorkspace] seiectFile:path 
lnFlleVlewerRootedAtPath:nil]: 

1 


- {lEAction]showSourceActlon:(Id]sender t 
NSString 'antiword = [[[NSEundle 
maitiBundleJ pathForResource antiword 

ofType 3 @""]stringByAppendingPathComponent:@”antiword.0.32.tar 
-gE"]: 

[self revealInFlnder:antiword]: 


- {IBAction)toggleDrawer;(id)sender I 

if ([drawer state]= NSDrawerClosedState) [drawer 
open 0 nEdge:N 3 MinYEdge]; 

else if ([drawer state] “ NSDrawerOpenState) [drawer 
closer nil] : 

] 

- [IBAction)showLogAction:(id)sender \ 

[[textLogView window] JuakeKeyAndOrderFront:self] : 


// dntg & drop routines 

// a stmidard w:iy it) name output files, l>ast:d on :m input n;niie: 

- (NSString ')filePorlnput;(nSStrlng ')docFile 
extension:(NSString *)extension [ 

HSFlleManager *fm = [UEFileManager defaultManager]; 
return [ftn nextUniqueNameUaing: [ [fm temporaryDirectory] 
StringByAppendingPathComponent3 [[fdocFila lastPathCotnponent] 
StrlngByDeletingPathExtensiDn]stringRyAppendingFathExtension: 
extension ]]]* 

I 

- (NSStting *)psFileForDocFlIeLdocFile I 

return [self flleforlnput:docFlle extension3@"ps"]: 


- (NSString *)pdfFileForDocFile:docFile \ 

return [self f ileForlnput'docFile extension 3@"pdf''] : 


- (BOOL]convsrtFlle:(NSStrlng ')docFile toFile:(NSString 
‘)psFiie \ 

fi call anti word with it tkinveniionjob instance: 

ConvetsionJob " job ” [ [ConversionJob 
aliocWithZone:[self zone]] initWithInputFile:(NEString 
*]docFile outputFile3 (NSEtring *)psFile 
landscape: [portraltLands'capeMatrix selectedTag] 
paperNante: [paperSixePopUp tltleOfSelectedlteitill ; 

//pending: QUEUES 

// wt“ may go thre^ttit^d litter... 

return [job doExecution3 self]; 


■ (BOOL)openFiIe;(NSString *)pdfFlle [ 

NSWorkspace *wm = [NSWorkspace sharedWorkspace] ; 
if (([[NSUserOefaults standardUserDefaults] 
boolForKey:^''DontOpenlnGreate’']) || ] [wm openFile:pdfFile 
withApplication:@”Greate'' andDeaotlvate: YES] } f 
return [wm openFilerpdfFile]: 

) 

return NO: 


//Ask PStiil to do convert the file: 

■ (BOQL)pstlllConvert:(NSString *)ps toFile:(NSString *)pdf f 
return convertFlles([NSArray atrayWithObject:ps] ^ pdf): 
f 


// Once the job finishes, this is ciiOed - let's give the user some feedback: 

- [void)taskTerminated:(BQOL)succesa outputFile:(NSString 
*)cJUtpout I 

if (success) I 

NSString 'pdfFile = [self 
pdfFileForDocFile tout pout]: 

(well setFiie:outpout]; 

[atatusField setStringValue :S''Success * click iinage 
to reveal in Findec''] : 

// We have a valid PS file * !efs begin the next step of ininshition to POE: 

if ([self patlllConvert:outpout toFile:pdfFile] ) [ 


// success? Let's give s<3me feedback and open the file: 

[well setFile:pdfFLle]; 

[self openFile:pdfFi'le] : 

I else [ 

[statusField setStringValue:@''PStlll had trouble 
see PStill's Log”]; 

[ 


I else i 

[well setFile:®^”]; 

[atatusField setStringV'alue;(?”Converted failed - see Log!”]: 
I 

I 

- (id)logText ( 

return textLogView: 

I 


- (ROOL)convertAndOpenFile:(NSString OdocFile 1 

NSString 'psFile ” [self psFileForDocFile:docFlle] 3 : 
[Gelf convertfile:docFile toFileipsFile] : 
return YES: 


// In order for your iipp to open files th:it iirc dniggcd upon the dock tile, you need to 
do two things 

// L impleinent - :ipplication: oj>enFile: in your NSApplications’s delegate class 
// 2. In Pil.spccily' valid I>ocument Types in Target inspector. Application settings 


- (BOOL)application:(NSApplication '[sender 
openFlle: (NSString Mpath 

f 

return [self convertAndOpenFile:path] : 

I 

@end 


//////// Convcrwonjoh.h /////// 
// 

// ConversionJob h 
// Doctor 
// 
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PROFESSIONAL SOFTWARE PROTECTION 


wvvw.eAladdirv.com 


HASP 

One Key, 

Multiple Platforms 

Now your cross-platform software enjoys cross-platform 
security. By preventing unauthorized software usage 
and duplication, HASP protects intellectual property 
rights and increases revenues across the board. A single 
HASP USB protects Windows. Linux and Mac applications, 
for reduced development time, simplified shipping logistics 
and lowered costs. Our cross-platform software proteokn 
key benefits your customers too - now they can use 
your application on muitiple platforms with maximum 
convenience. More developers than ever rely on HASP 
to increase revenues, 

HASP supports: 

• Windows IX/95/98/ME/2000/NT4/XP • Linux 
• MacOS8.6-9,x • Mac OS X 
• TCP/iPJPX, NetBIOS-based networks 



w w w. e AI a d d i n * c o m / m a c t e c h 
or call 800-223-4277 ESI 
& 800-562-2543 PST,CST,HST 



SECURING THE GLOBAL VILLAGE 


// Created by andrew on Tim Apr 12 2001. 

a 


typedef enmo f 

Convers ioTiKeeds Inf o t 
ConversionReadyToBegin. 

ConversionBusy, 

ConvereioitDone, 

ConversionAbortEd. 

ConversionError 
) ConversionStatus; 

©interface ConversionJob: NSObject <NSCapyiiig> 
I 

NSStrlng 'InputPath; 

NSString 'outpntPath; 

NSString •statuEString; 

NSString 'paperNaine; 

BOOL _lsLandacape; 

ConversionStatuE conversionStatus: 

] 


// clasii methods let the Ul determine what can really be c<mverted; 

+ (NSArray *}convertibleFileTypes; 
i (BOOL] canConvertFile: (HSString '^Ipath; 

• {void}abort; 

// ihb is Ccmversioiijob’s designated initisiiJier 
- (id) initWithlnpntFllE: {NSString ')dt)CFile 
outputFile:{NSString ‘)pBFile landscape:(BOOL)landscape 
paperNama;(NSString *}paper; 


// these represent the various panimters to ;i conversion: 

• [void)BetLandscape:(BOOL)bin: 

- [BOOL)landscape: 

• (NSArray * ] argmnerits; 

’ {itit} doEjcecntion: {id) delegate : 

- (NSString *)inputPath; 

- (void)SEtlnputPath:(KSSttlng ‘)path; 

- {NSString OoutputPath; 

• [void)setOutputPath:(NSString ')path: 

- {NSString *)valldOutpntPath: 

• (NSString *)statnsString: 

- (void)sEtStatUEString:(NSString *)status: 

• (NSString *)paperHaine; 

- (void)setPaperNaae: (NSString *)naiiie; 

’ (ConversionStatusJ convErsionStatns: 

- (void)setConversionStatuB:(GonversionStatus)status: 


extern NSString *JobStatnsDidGliangeNatlflcation; 
Send 


//////// Cbnversionjob m /////// 
if 

if <]onversionJob.m 
// 

// 

// Created by andrew on Thu Apr 12 2001. 

// Andreiv C. Sttme and Stone Design Corp 
// 

{^include <stdlo-h> 

^include <stdlib.h> 

/Kinport (Carbon/Carbon *h> 

//import (Cocoa/Cocoa*h> 

//import ’'NSFlleManager-Extensions .h" 


^import "ConverslonJob.h" 

//import "DRController 
//import “SDLogTask.h“ 

©implementation ConversionJob 

NSString *JobStatnsDidChangeNotlflcation = 
JobStatusDidChange": 

/' 

Usage; antiword [switches] wordfilal [wordfile2 
Switches: [-t|-p papersize] I-m mapping][-w #] [-i 
#] [-X #] [-Ls] 

-t text output (default) 

-p (paper size name) PostScript output 
like: a4, letter or legal 
-V (width) in characters of text output 
-i (level) image level (PostScript only) 

-m (mapping) character mapping file 
-X (encoding) character set (Postscript only) 

-L use landscape mode [PostScript only) 

-s Show hidden (by Word) text 

'/ 

//Wc live in a world of both file extensions AND traditional Mat types - Sij let's look 
for both: 

+ (NSArray OconvertiblsFlleTypss t 
return [NSArray 

arrayWithOb jects: ©*^doc" . NSFileTypeFeirHFSTypeCode(' WDBN 

■},nil]; 

1 

f (BOOL)canConvertFile;(NSString ‘)path ( 

NSString ‘extension = [path pathExtension]: 

// IF there is no extension, lets see if there is a Mat Type; 

If [IS_KULL(extension)} extension = 

NSHFSTypeOfFile(path): 

if ([[self convertlbleFileTypes] 
containsObject:extension]) return YES: 

return NO; 

I 


- (id)inii [ 

self = [super init]; 
if (self) [ 

inputPath = 
outputPath “ 
statusStrlng ” 

conversionStatus = ConversionNeedsInfo; 

I 

return self: 

I 

// the designated initializer 

- (id)InitWithlnputFileI[NSString ‘)docFile 
outputFile;[NSString *)outpath landscape:(BOOL)landscape 
paperName:(NSString *)paper: 

I 

self = [self init]; 

inputPath = [docFile copyWithZonei[self zone]]; 
outputPath = [outpath copyWithZone:[self cone]]: 
paperName = [paper copyWlthEone:[self zone]]: 
_lsLandscape = landscape: 
return self; 

t 


// Don’t litLcii 

- (void)deailoc I 

[inputPath release]; 
[outputPath release]; 
[statusstring release]; 
[paperName release]; 
[super dealloc]: 
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// nott that we do not copy status or stitns string! 

- tidJcopyWithZone:(NSZone ‘)20De ( 

ConversionJob 'newJab = [fConvecsionJob 
allocWitliZoiie:zoneJ init]; 

[newJob 5 etIuputPath:inputPatbl: 
tnevJob setOutputPath:outputPath]; 
In^wJob setPaperNaraetpaperWameJI 
[newJob s et Lands cape :_lsLan.dscape]; 
return newJob: 


U sets and gets 

- (NSString OpaperName I 

return paperKame: 

] 

- (void)setPaperbtaiieI (NSString *)patb ( 

if (![patb isEqualToStringipaperName]) [ 

[paperNarae release]| 

paperName = tp^th copyWithZone:[self zone]]: 

[self setGonversionStatus:CanyersionReadyTDBegin]: 

1 

] 


- (void)setLandscape:(BOOL)bin i 

_isLandscape = bin; 

] 

- (BOOL)landscape j 

return _isLant!scape: 

1 

■ (NSString ‘)inputPath [ 
return inputPath: 

] 


- (void)setlnputFatb:(NSString ')path I 

if ([[path lsEqualToString:iTiputPathl) [ 

[inputPath release]: 

inputPath “ [patli copyWithZone: [self zone]]: 

[self setConversionStatus:ConversionReadyToBegin]: 



- (NSString ^)outputPath I 
return outputPath; 


’ (void) se tout put Path: [NSString *}patli ( 

if ([[path isEqualToStrlngioutputPath]) I 
[outputPath release]: 

outputPath ” [path copyWithZoner[self zone]]: 

) 

I 

+ (BOOL)pathVaiid:(NSString *]path [ 

BOOL isDlr: 

return [NOT_NULL(path) firi [ [NSFlleManager defaultHanager] 
f ileExistsAtPath: path IsDirectory :lE^isDir] &iSi isDir Sfii 
[ [NSFileManager defaultHanager] isWritahleFileAtPath:path)): 

I 

- (NSString *)defaultOutputFolder:(NSString *)iiextTDlnput 1 

return [ [NSFlleManager defanltManager] 
temporaryDirectory]: 

I 

- (BOOL)canWriteTo:(NSString *)file I 

return [[HSFlleManager 
defaultHanager]isWritableFileAtPath:[file 
stringByDeletingLastFathComponent]]: 

] 



Fetch 4.0 


Woof. 



Fetchsoftworks.com 

More Features * Fewer Bugs 
Bigger Icon 
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//This mtrthod will creatt a valid output path; 

- (USString *)validOutputPath ( 

static int unique ^ Or 

if (N0T_NULL( out put Path) itSs [self canWriteToroutputPath]) 
return outputPath: 
else I 

[self setOutputFath:[[[NSFileManager defaultManager] 
teinp 01 aryE) 1 rectory] stringByAppeudiugpathComponent: [NSString 
stringWithFormat: . [ [InputFath lastPathComponent] 

EtringByDeletingPathEsnrenaion] ,+-hinlque> [inputPath 
pathExtension]]]]; 
return outputPath; 

} 

1 

- tNEString *)BtatusEtrlng ( 

if (K0T_NULL(statusstring)) 
return statusStrlng; 

else I 

switch [cotiversidnStatus) I 

case ConversionNeedsInfer 

return NSLocaIizedStringFrotiiTable[@"Awaltlng 
Input Font or Folder - drag one on!DOG"status string 
when Info is still needed"): 

caae ConverslonReadyToBegln: 
return 

NSLocalizedStrlngFromTable(@"Initialising 
Job" .#"D0C" . S'"status string when job starts'*); 
case ConversionBusy: 

return [NSString stringUithForiiiat 
1^04 N." .HSLocallzedStringFroinTahle (©'^Converting" 
us string when conversion is happening"),[inputPath 
lastPathComponent] ]: 

case ConversionDone; 
return 

NSLoc3lisedStringFroniTable(@"Converslon complete - drag it 
out!".©"DOC".©"status string when conversion is done"): 
case ConversionAborted: 
return 

NSLocaiizedStringFromTable(©"Conversion was 

stopped "*©'■ DOC" .©"status string when conversion is stopped"): 
case ConversionError: 
default: 

return NSLocalisedStringFromTable(©"ERROR! 
See Log. ".©"OOC" .©'* status string when error converting"): 



(void)abort I 
//PENDlNTckill ihcjob! 

[self setConversionStatus:ConversionAbortedI; 

) 

• (void)setStatusStrlng:(NSStrlng ')status [ 

if Cl [status isEqualToStringistatusStringl) ( 
[statusString release]: 

Statusstring “ [status copyiJlthZone: [self zone]]: 

I 

I 


- (ConversioiiStatus)conversionStatuE I 

return converslonStatus; 

I 

- (void)setConveraionStatus:(ConversionStatus)status f 

conversionStatus * status: 

[ [NSNotificationCenter defaultCenter] 
p 0 s tNot i f i cat i on Name: J ob St at us D i d Cha n geN ot if i ca t i o n 
object: self]: 

I 


’ (NSArray *)arguments [ 

KSHutableArray *args = [NSMutableArray array]: 

[args addObject'p"]: 

[args addObject;paperNaine] : 

if (_isLandscape) [args addObject:©"-L"J : 
[args addObject:inputPath]: 

// future options can be added here,., 
return args: 


// 

// Here is the callliack from SDLogText 
//Well pass it on up to IlRContioller 
// 

^ (void)taskTerminated:(BOOL)success 

t 

[[NSApp delegate] taskTerminated;success 
outputFlle:outputPath]: 

\ 


(int)doE35:ecution: (id)deiegate ! 

volatile int statusAtCompletion ^ 1: 

// wt place each execution inside of it's own NSAiiiorelcasel^Kti 

NSAutoreleasePool * pool ^ [ iNSAutoreleasePool alloc] 
Init]: 

// the actual executable is inskle the folder antiword' 

NSStrlng ‘antiword ” [(NSBundle 
mainBundle]pathForResource:©"antiwa-rd'' ofType;©""] : // the 

folder! 

[self setConverBlonStatussConversionBiisyl; 

[self validOutputPath]; 


// He re Si my grcKJvyTa.sk wnipptT which l<)g,s ernirs: 

// the one interesting varialde fs the dictionar) p;Ls.scd into the environmenL: 
//We need to set the HOME (where the resources will be soughi by aniiword) 

// 

I [SDLogTask alloc] InltAndLaunchWithArgs: [self 
argumentfil executable;[antiword 
stringByAppendingPathComponent:©"antiword"] 
directoryiantiword 

logToText:[[NSApp delegate] logText] 
includeStandardDutput:NO outFile:outputPath owner;self 
environment:[NSDlotionaty 

dictlonaryWithObjectsAndReyalantiword, ©"HOME"*nill ]: 


[pool release]: 

return 1: 

I 


©end 


//////// SDLogTaskJi /////// 

P SDLogTask. h tTcated by andrew' on Thu 3tKApr 1WB 7 
// 

//A wmpper of some intense mullkhreaded code 
//To aMow you to spawn a task and see the errors 
// 
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Your Data Isn’t 
an Important Part 

of the Job 

— It IS the Job. 


VXA FireWire 


can stick 
my entire 
hard drive 
onto a tape 
7 times 
—thot's yust 
plain cool!** 




Other backup media, such as CD-RWs and DVD-RAMs, 
simply can't compare to VXA-1 tape technology when it 
comes to capacity, transfer rate and overall price. 

Fast, economical and easy-to-use, 

VXA FireWire offers: 


The High-Performance 
Tape Storage Solution 
For Apple Users 


Ultimate File Security 

• 100% Data Restore and Interchange 

• Rug-and-PI^ Connectivity 

Sharable Media 

• Multi-Gigabyte Fife Transport 

• Portable, Hot-Ruggable 


Technology 

Capacity 

in liBs 

Transfer Rate 

In HD/sec 

Price 
per MB 

VXA Tape 

33000 

3 

$0.03 

ImattonTrawn 

10000 

1 

$0.05 

DVDRAM 

9400 

17 

$0.0$ 

CD RW 

700 

L9 

$0.50 

Zip 

250 

1.2 

$0.76 


Real Time Digital Video 

Cross-Platform Compatibility 

• FireWire/IEEE 1394/iLink Supported By 
All Major Manufacturers 


Call Exabyte sales at 1-800-774-7172 
or visit us on the web at www.exabyte.com 

Tape Storage By 

^VXA^ 2 Exabyte' 


© Copyright 2002 Exabyte Corporation . All rights reserved. VXA andVXAtape are negistened trademarks of Exabyte Corporation. 









#liDport <AppKlt/AppKit*ii> 


l&interface SDLogTask : NSObject 

[ 

Id owner: 

NSTextView *logText; 

KSTask *taak: 

BOOL includeStandardOutput: 

KSString 'oiitFile; 

USPipe ‘standardErrorPlpe; 

NSPipe 'standardOutputPlpe: 

NSFiieHandle *standardErirorHaiidle: 

HSFlleHandle * standardOutputHandle; 
NSFlleHandle *outptitFlleHandle: 


// 

// exeaitable is full path ta ptt^m 

// is an array of strings of tlie arguments 

// send in an NSTextView if you want console behaviour 

// indutleScandardOut: is YES if you also want stdout logged to Test 

if 


- (id)initAndLaunchWithAEgs: (NSAtray *]args 

executable:[NSString MpathToExe directory:(NSString *)dir 

logToText:(NSTextView *)text 

IneludeStandardOutput:(BOOL) includestandardOut 

outFile:CNSString *)outFile ownerlanOwner 

envlrorunent;(NSDictlDuary *)environment: 


4 Evoid)appendEtring:(NSString ‘)string toText:(NSTextYiew 
•)tV newLine:(BOOI)newLine: 

@end 


//////// SDljogTask-m /////// 

// 

r SDL)gTask.m created by antlrew onlTiu 30-Aprl99B 7 


^import “SDLogTask,h'' 

// kudo?' to bbum^ctidcfabuom for helping me ftx 10: 
f/import ‘*NSFileHandle_CFRNQnBlockingIO.h“ 


if Cfttv window] isVisible]) I 

[tv scrollRangeToVisible:END_RANGE]; 


I 


] 


- (void)appendstring:(tiSString *)string newLine:(BOOL)newLine 
f 

[[self class] appendString:string toTexttlogText 
newLine:newLine]: 

1 


- (void)outputData:(NSData •)data 

\ 

[self appendstring:[[[NSString alloc]initWithData:data 
encoding: [NSString defaultCStrlngEncodingl]autorelease] 
newLine:YES]: 

1 


- (void) proceasAvailabieData: 

NSData *data: 

BOOL dataProceased: 

NSJURING 

dataProcessed * NO: 

data = [standardErrorHandle availableDataUonBlocking] : 
if ( (data != nil) kh ([data length] != 0) ) I 
[self outputData:datal: 
dataProcessed “ YES: 

I 

NS_HANDLER 

dataProcessed ” NO: 

NB_ENDHANDLER 

NS_DURTNG 

if (IncludeStandardOutput) f 

data = [standardOutputHandie avatlableDataNonBlocking]: 
if ( (data 1“ nil) && ([data length] 0) ) [ 

[self outputData;data]: 
dataProcessed = YES: 

!■ 

I 

NS_HANDLER 

dataProcessed = NO: 

MS_ENE HANDLER 


// 

// II’ ytiu wim notlEciitjcjn when the task cumpJcti;a. 

// implement this method in the “owner*" class 
// 

©interface NSObject(SDLagTask_DelEgatE) 

- (void)taskTerminated:(BOOL)success; 

©end 

©implementation SDLogTask 

- (void)dealloc 

f 

if (outFlle) [outFile release]: 

[super dealloc]: 

I 

// 

// Methods to make ii easy to spew feedback tt> user: 

// 

^define END_RANGE NSNakeRange([[tv string]length].0) 

4 (void)appendString:(NSString *)string toText:(NSTextView 
*)tv newLine:(BOOL]newLine; 

( 

[tv repiaceCharactersInRange:END_RANGE 
withString:string] : 

if (newLine) 

[tv replaceCharactersInRange: ENDURANCE 

withString:©''\n”] : 
else 

Itv replaceCharactersIuRange:END_RANGE 

withString:©" “]; 


if ([task isRunning] “ YES) I 
If (dataProcessed YES) 

[self perfortiSelector: ©selector(processAvailableData) 
wlthObject: nil afterOelay: ,1]; 
else 

[seif performSelector: ©selector(processAvailableData) 
withObject: nil afterDelay: 2,5]; 

1 

1 


- (void) .outputInfoAtStart:[NSString *)pathToExe 
args:[NSArray *)args 
I 

int 1: 

// clear it out frum last time: 

// [ logTcxt setstring: @|; 

[self appendstring:pathToExe newLine:N0l: 
for (1=0: i < [args count]: 1++) 

[self appendString:[args objectAtIndex:i] newLine;NO]; 
[self appendStringi@"\n" newLine:YES]; 


- initAndLaunchWithArgs:(NSArray *)args executable:(NSString 
'IpathToExe directory:(NSString ‘}dir logToText:(NSTextView 
*)text includestandardQutput:(BOOL)includeStandardOut 
outElle:(NSString *)an0utFile ovner:an0wner 
environment:(NSDictionary *)environment 
( 
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[super init]: 
logText = text: 

includeStandardOutput “ InciudeStandardOut; 
outFile = [anOutFile ropy]: 
owner ^ anOwner: 


standardErrorPipe = [NEEipe pipe]■ 
standardErrorHandle = [standardErrorPipe 
fileHandleForReading] ; 


if [(outFlleS^ail] && J (outFile 
isEqaalToString:®”"]] ! 

I [NSFileHanager defaiiltKanager] 
reffiOVeFileAtPath:nutFils handler:nil]: 

if ([ [MSFileManager defaultHanager] 
createFileAtPathtoutFile contents:[MSData data] 
attributes:nil]) 

outputFileHandls - [NSFileHandle 
fileHandleForWritingAtPath^outFileJ : 
else [ 


NSLcig(®""Cannot open %@] 

Aborting..,outFile); 

if ([owner 

respondaToSelector:@selector(taskTennlnated:)]) 

[owner taskTerminated:0]: 


return nil; 


false if [includeStandardOutput) f 

standardOutputPipe " [NSPipe pipe]: 
standardOutputHandle = [standardOutputPipe 
fileHandleForReading] : 


1 

task = [[NSTask alloc] init] ; 


[task iatinch] : 

[[NSNotificationCenter defaultCenter] 
addObserver: self 

selector: ^selector[checkATaskStatue:) 
name: NSTaskDidTerniinateNotlflcaticin 
object: task]: 
return self: 


f 

#define TASK_SUCCEEDED NSLocalizedStringFroniTable(@"Job 
SUCCEEDED 1 \n'l ^"Packlt'l ""message when task is successful”) 

/Mefine TASK^FAILED NSLocalizedStringFromTableJob 
FAILEDJ\nFlease see log.", @"PackIt". "when the task 
falls.,.") 


‘ (void)checkATaskStatus:(NSNotification *}aNotification 
t 

int status = [[aNotification object] terminationStatus] : 
if (status "= 0 /* STANDARD SILLY UNIX RETURN VALUE */] i 
[self appendStting:TASK_SUCCEEDED newLineiYFS] ; 

\ else [ 

[self appendString:TASK,FAlLED newLine:YES]; 

[[logText window] orderFront:self] : 

f 

if (outputFileHandle 1“ nil) 

[outputFileHandle release] : // this wUl dose it according to docs 

If [[owner respondsToSelector:@selector(taekTerminated:)]} 
[owner taskTerminated:[status =0]]; 

1 


[task setArguments:args]; 

[task setCurret3tDirectotyPath:dir] ; 

[task setLaunchPath:pathToExe]: 

[task setStandardError:StandardErrorPipe] : 

if (environnient nil) [task setEnvirontnent:environment] ; 

if (outputFileHandle 1= nil) [task 
setStandardOutput routputFileHandle]■ 
else if (includeStandardOutput) [task 
setStandardOutput:standardOutputPipe]: 

[self outputlnfoAtStart:pathToE-xe args:args]: 

[self perforntSelector: ^selector(processAvailableData) 
vithObject: nil afterDelay: 1.0]; 

// iiERE WE GO: spin off a thread to do this: 


@and 

Diagnosis 

As of this writing, anti word's -i and -X flags are not 
SLipponed - this would be a nice enhancement for DOCior to 
be able to specify alternate encodings and the level of PS 
compliance. Another useful addition would be to provide a 
simple text translation using the -t option, as well as having 
the U1 process folders of files instead of just one at a time. 

One of Cocoa’s great strengths is the ability to quickly 
wrap traditional command line programs into mere mortal 
usable graphical user interfaces — I wrote DOCtor in an 
afternoon, reusing some standard Stone components. 
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APPLESCRIPT 
AMD COCOA 


By Bill Cheeseman, Qmchee, VT 

AppleScript Studio: Implementing an 
Application Preferences System 


Saving and Retrieving Application 
Preferences in AppleScript Studio 


We provided an overview of AppleScripi Studio in the first 
article in this series, AppieScnpt Studio: An Inlroduciioth In the 
second and third articles, we will w^ork whth Sir Arthur Conan 
Doyle to solve the mystery of how to create, open and save 
documents in AppleScript Studio, 'fhe existing documentaiion 
does not cover this, but an important clue suggesting that it can 
be done is already in the evidence room: t>ne of the three 
standard AppleScript Studio templates is named '‘AppleScript 
Document-based Application.” Although the Watson example 
that forms the basis of the AppleScript Studio tutorial uses this 
template, neitlier it nor any of the other examples actually 
addresses the mystery . In the course of our detective work, we 
will llicrefore help Sir Arthur to w rite an example application of 
his own. We will name it ‘‘Doyle” in his honor, carrying the 
current fad of naming applicatkms after Sherlock ffolmes 
characters to its logical conciusion. 

Tile Doyle application W'ill need a preferences file. T he first 
.solution an AppleScripler thinks of wiien the .subject of 
preferences comes up is to use a property. However, the Rehase 
Notes for the First version of documentation for AppleScript 
Studio mentions that AppleScript properties do not retain 
changes to tlieir values between relaunches of the application. 
This is contrary to the normal l>ehavior of AppleScript properties 
(and, for that matter, of AppleScript global variables, which also 
retain their values across repeated launche.s of a .script or script 
application), A future release of AppleScript Studio will 
presumably restore the persistence of AppleScript properties. In 
the meantime, but AppleScript Siudio is likely to retain this 
unfamiliar behavior due to technical requirements of application 
bundles in Mac OS X. In place of properties, the AppleScript 
Studio Release Notes documentation recommends that “if you 
w'ant persistent storage of values, write them to a preferences 
file." We will therefore include in Doyle the ability to create, 
open and save a preferences file, wliich provides a simple 
intrtjduction to the use of documents in AppleScript Studio. T'he 


exercise w ill prove valuable even if properties eventually resume 
their accustomed behavior, since preference Files can be useful in 
any application of even modest ctjmplexity. 

We will tackle the mystery^ of documents in two installments. 
In the First in-stallnient, we will devLse an AppleScript-based 
preferences system in response lo the injunction in the Release 
NotesdocumenUitknL In the second, we will expand the example 
application to handle more complex documents in a more 
Cocoa-like fashion. 

Unlike Sir Arthur's novels, ihe cunem mystery does not have 
only one solution. There are many ways to save and retrieve 
infumiation in AppleScTipt Studio, as in Cocoa applications 
generally. This article offers one solution among many. In 
particular, version 1.1 of AppleScript Studio makes Cocoa's built-in 
preferences system, NSLIserDefaults, readily available to 
AppleScripiers, but we will nevertheless use traditional AppleScript 
techniques based on the AppleScript Read'Write commands to 
implement preferences here. It is important for Cocoa developers 
new to AppleScript to know' how this light-weight 
AppleScript document management teeluiique can he used. In the 
second installment* AppleScripters new to Cocoa will learn the 
Cocoa w'ay to manage documents. 

This article and the next will include complete listings of 
the AppleScript statements in the Doyle application, in order to 
keep the scripts as simple as possible, w'e will make no attempt 
to deal with internationalisation and localization, and we will do 
no error Lrapping. 

The Ai'pleScrifi' Document-based Appucation Template 

The first step in writing any AppleScript Studio application 
i.s to create a new^ project in Project Butlder, using it.s File -> New 
Project menu item to .select one of three .standard templates. Do 
this now, and choose the AppleScript Document-based 
Application template. Save our new' projeti under the name 
“Doyle" wherever you keep your .scripting projects; your 
Documents folder wkll do. 

Before deciding what w^e need to add to the template, it will 
be useful to build and mn the template as is, without any 
changes, to see what already works. Do this now by clicking the 
Build and Run button in Project Builder. An empty window 


BiU Cheeseman is a retired lawyer now making hi,s living as a Macintosh developer and loving every" minute of it. He is uniquely qualified to write 
about AppleScript Studio* having served as webmaster of The AppleScript Sourzehook (www.AppleSctiptSoLJrcebook.com) for many years and having also 
written a Cocoa tutorial, Vermon! Recipes- A Cocoa ( www.stepwise.conn/ Articles/ VermontRedpesy). 
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named ‘^Untitled” appears. This is in accord with the Aqua 
Human Interface Guidelines, which specify that launching an 
application or bringing a running application to the front (for 
exampIcj by clicking its icon in the Dock) should open a new, 
untitled window if a window lielonging to the application is not 
already open, and it .should deminiaturize a window' if the only 
open window is currently miniaturized in the Dock. 

The new window^ contains no controls, but our application 
does have a menu bar, so let's try out some of its menu items. 
About Application, under the Application menu, brings up an About 
dialog. Like several of the menu items, the About dialog contains 
dummy information. We will shortly customize the menu items 
and the About dialog using Interface Builder, but we won't have 
to wTite any scripts to make them work. Help -> Application Help 
brings up a dialog staling that the application doesn’t have any 
help. We'D leave that alone in these two anicles. 

The menu that interests us in these articles is the File menu, 
with its liuiltdn New, Open, Close, Save, Save As, and Revert 
menu items. Try them out. Choose File -> New; a new empty 
window appears, named “Untided 2/ Choose File -> Close; the 
new window closes, leaving the original ‘"Tlniitled"' window in 
place. Choose File -> Save or Save As; a standard file saving sheet 
opens with all die usual features, allowing us to give the 
document a name and select a location w here it should be saved. 
This is getting worrisome, for it is beginning to appear diat there 
may he no mystery for us to solve! 

Continuing with the investigation, name the untitled 
w'indow^ “Test" and select your Documents folder as the place to 
save it. Another sheet promptly appears, saying “Couldn't Save 
Document." “Aha!" says Sir Arthur, “Here’s a myster>'. Holmes 
will have to write a script or two to save this document,” 

Laying the GroliNdwork 

Before figuring out how to save the document, we will have 
to help Sir Arthur decide why Holmes would want to save it in 
the first place, by specifying a task that requires saving and 
retrieving information. Let's have Doyle (the application) save a 
log documenting the course of the investigation, recording the 
date and time of every occasion when a user launches or quits 
Doyle. To make it more useful, well also allow the user to open 
the log and edit it by adding comments to each entry, in case 
some detectives prefer to let the evidence speak for itself, we'll 
also give Doyle a Preferences window in which the ability to 
edit the log can he turned on and off. It is this last feature, the 
Preferences window, that we will tackle in this article, leaving 
the Doyle Usage Log to the next installment. 

The basics of building an AppleScript Studio application are 
covered well in the dcxumentation and need not be repeated 
here except in brief outline. 

First, castomize the menu bar. With our new Doyle project 
open in Project Builder, mouse over to the Groups 8l Files pane 
on the left side of the project window, selecting the Files lab if 
necessary to open it. Expand the Resource.5 group, and double¬ 
click MainMenu.nib, one of the files that conies with the template. 
Interface Builder launches and opens the new application’s main 


menu. Following the steps outlined in the AppleScript Studio 
documentation, change several of die menu items so they refer to 
""Doyle" instead of “Application.” Don/L change the name of the 
Application menu itself, however; it will automatically take on die 
name of our application w-hen w^e run it. Don't forget to save 
frequently and, w^hen youTe done, close the Main Menu, nib file by 
clicking die MainMenu.nib Windows’s clOxSe box. 

Next, customize the About box. Click Credits.rtf in die 
Resources group of the Groups ik Files pane in the Project 
Builder window, and type any appropriate information 
identifying the team that built Doyle. 

Finally, click InfoPlist.strings in tlie Resources Group and 
provide new values for the four variables you find there, following 
the model of die dummy strings in die template. Basically, just 
change “Application" to “Doyle" wherever it appears, and change 
the name of the author in the copyright notices so that some fake 
company doesn’t get credit for our work. 

Designing the Windows 
The Doyle Usage Log Window 

Although the detaiLs of implementing the Doyle Usage Log 
will be left to the next installnient, we will design the main 
document window now to give us a sense of our application's 
look and feel. Double-dick Documeninib in the Project Builder 
window’s Re.sources group tu tipen it in Interface Builder. If you 
don't .see the empty document window at first, double-click tlie 
Window' icon in the Instances pane of the Documeninib window 
to bring it to the front. Also, for convenience you can open the 
Info panel now by choosing Tools -> Show Info. It is very helpM 
to have this panel open all the time; for this reason, an Interface 
Builder preference exists to Show Info Window at Startup, but it is 
turned off by default. 

With the document window' open and selected, use the 
Attributes pane of the RSWindow Info panel to set the 
window'’s tide to ""Doyle Usage Log." Also, select buttons and 
checkboxes in the Info panel as needed to set the window's 
Backing to Buffered, its Controls to enable Miniaturize. Close and 
Resize, and its Options to enable Visible at launch time. Deferred, 
and One shot. The meaning of most of these settings is obvious 
from their names. You will rarely, if ever, need to change the 
default settings of those whose meaning is not obvious. 

From the Cocoa-Data palette, drag a table view into the 
document windtjw and place it near the top left comer, using the 
Aqua guides to position it precisely in accordance with the Aqua 
Human Interface Guideiines. Drag the table view’s bottom right 
resize handle to make the table fill the window to the right Aqua 
guide and far enough from the bottom to leave room for a row 
of buttons. There is no Aqua guide to leave room in advance for 
die buttons; you w'ill have to readjust the table view in a 
moment, after adding a button. Create a third column in the table 
view and name the columns, from left to right, “Date," “Action,” 
and “Comments," using techniques described in the AppleScript 
Studio documentation. Also, size the left column to hold a date 
and the center column to hold the word “Run" or “Quit." Finally, 
select checkboxes in the Info panel to set the table view's 
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.Selection to Allows Empty Selection, Allows Multiple Selection, and 
Allows Column Selection, its Scrollbars to Vertical and Horizontal, 
and its Options to Allows Resizing, Display Column Headers, and 
Autoresizes Columns to fit. Other items should be deselected, 
including Allows Reordering because we want the log to remain 
in chronological order. 

Drag a standard push button from the Cocoa-Views palette 
to a position near the bottom right corner of the document 
wrindow, lining it up with the aid of tlie Aqua guides. Name the 
button “Delete,’* The button may resize itself to accommtxlate 
the length of its new title, so you might have to readjust its 
po.sition afterwards. You can also now drag the liotlom edge of 
the table view to position it the proper distance above the 
button, using the Aqua guides that have now become available. 

The Preferences Window 

Now we are ready to design the Preferences window. Close 
Document.nib to get it out of the way for now by clicking its close 
box, saving it if asked. Still in Interlace Builder, choose File -> 
New; the Starting Point dialog opens, if it wasn’t already open. 
Select Empty under the Cocoa topic and click the New button. A 
new, untitled Interface Builder nib window opens, with the 
Instances pane selected and containing File's Owner and First 
Responder icons. For convenience, save it now, before making 
any changes, by choosing File -> Save As. Give it tlie name 
“Preferencesmib” and navigate to save it in the English.Iproj 
subfolder of the Doyle project folder Leave the checkbox 
unselecied .so that the file extension will not he hidden. When a 
sheet appears, dick the Add button to add the new nib file to the 
Doyle project and target. If this sheet does not appear, you saved 
the nib file in the wrong place; this can ea.sily be cured by using 
Project Builder’s Project -> Add Files command, preferaidy first 
dragging the new' nib file into the correct location using the 
Finder in order to keep all the project files in one place. After it 
appears in the Groups & Files pane of the Project Builder projed 
wintlow, it is convenient to drag it into the ltest>urces group if it 
isn't already there. The small checkbox button to its left should 
Ix" selected, indicating that the file w'ill lx- included in the target 
when the application is built. 

Select the File’s Owner icon in the Instances tab of the 
Preferences.nib window and, in the Attributes pane of tiie File's 
Owner Info panel, select NSApplication to make the application 
object the owner of this nib file. If a dialog appears warning you 
that .something evil will liappen, you haveiTt succeeded in 
adding the Preferences.nib file to the project. You can prcxeed 
with the design t)f the window anyway, but l>e sure you 
remember to add the file to the project later using Project 
Builder’s Project -> Add Files command. 

Drag a window icon from the Cocoa-Wtndow^s palette into 
the Instances pane of the Preferences.nib window. A Window icon 
appears in the Instances pane and an empty window appears on 
tlie .screen. Using the Attributes pane of the NSWindow Info 
panel, give the window the title “Preferences" and configure its 
settings as you did with the document window, w'ith these two 
exceptions: die Resize checkbox in the Controls area should be 


deselected, as .should the Visible at launch time checklx^x. 

Finally, drag a checkbox (or “switch," as it is sometimes 
known in Cocoa) from the Cocoa-Views palette to the top left 
comer of the Preferences window, and rename it “Show 
Comments in Usage Log." Then, resize the window to make it 
smaller, until the right Aqua guide indicates that you have the 
correct margin on the right and until the bottom edge is as close 
to the top as you are allowed to drag it. With the checkbox still 
selected, use the NSButton Info panel to select the Selected 
checkbox in the Options area. We will set the Show Comments in 
Usage Log preference to true by default in one of Doyle’s scripts 
in just a moment. 

Save the Preferences.nib file but leave it open. We are now 
ready to start scripting. 

Scripting tup Applic:ation 

We will Stan by scripting the Prelerences window, because 
it reflects a single value that must be read by the main document 
w'indow Irefore the latter is opened. We will set up the 
Preferences w'indow and scripts for setting and getting its one 
preference value first. In subsec[Uem sections, we will take care 
of coordinating Ihis preference value and the user interface, and 
we W'ill arrange to save this value to di.sk in a preferences 
dcKTJmerit and retrieve it when the application is launched. 

Managing the Preference Value 

We now have a Preferences w'indow that will allow' the 
user, by clKxking or unchecking a checkbox, to specify 
W'hether comments are to be shown in the Doyle Usage Log. 
Next, we need to provide a means to hold this preference 
value—taie or false— within the application, so drat it can be 
looked up ever>' time the user opens the Log. An easy way to 
do this w'ould be to rely on the state of the checkbox itself as 
a record of the stale of the preference item, but we won’t do it 
that w'ay. For many reasons, data values should almost always 
he stored separately from the user interface. Here, we wall save 
the value of the application’s single preference item in a dLsk- 
haseii preferences file. 

We will not use Cocoa's built-in application preferences 
system, based on the NS Use rDe faults class, but will instead store 
Doyle’s preferences as an AppleScript record u.sing the 
Kead/Write commands implemented in the Standard Addition.s 
scripting addition. In the first release of AppleScript Studio, the 
Cocoa application preferences system is not available to 
AppleScript. Hie AppleScript Studio engineering team has 
informally made available a temporary workaround for using it, 
in die expectation dial and AppleScript acce.ss to Cocoa’s 
NSUserDefaults class will become is a built-in feature in a later 
release AppleScript Studio l.I. Even then, hHowever, there may 
be reasons lo prefer a pure AppleScript solution in some 
siruatioas, so w'e will develop one here. 

As the AppleScript Studio documentation very briefly 
suggests, it is generally a gcxxl idea to follow the Model-View'- 
Controller, or MVC, design pattern, w^hereby die Model (consisting 
of the application’s data and data management algorithms) is kept 
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separate from the View (the application's graphical user interface). 
The MVC paradigm is particularly important in Cocoa applicatioas, 
because the Cocoa frameworks are built around the concept and 
depend upon it in a variety of ways. It may be less important in an 
AppleScript Studio application, where the event handlers are 
already laid out according to the AppleScript object model and the 
structures of a Cocoa application. We will neveitheless follow the 
MVC paradigm here by storing and manipulating our single 
preference value in one script, called PreferencesModeLapplescript, 
while coordinating the preference item and the user interface in a 
second script, PreferencesControHer.applescript. 

If, after reading thi.s article, you adopt this .system and create 
an application of your own having many preference items, you 
will be thankful that you started out this way. It will allow you 
to keep all of the preference item data and handlers to 
manipulate it in one script, while isolating handlers to update 
the user interface and to obtain information from the user about 
the preference items in a separate script. Although it isn't 
necessary to create separate scripts in this manner in AppleScript 
Studio, getting in the habit of breaking scripts into smaller pieces 
according to some reasonable plan will help you to keep the 
scripts manageable as your application grows larger Here, if you 
later change the user interface, you will at most have to revise 
the Controller script; the Model script will continue to w^ork 
without change. Likewise, if you later rearchitect the data storage 
strategy, you will at most have to revise the Model script [>ui can 
leave the Controller script and the re.st of the application alone. 

Our strategy for implementing these tw{> scripts will be 
dictated by the fact that AppleScript properties and gloiial 
variables do not retain their values acro.ss relaunches of the 
applicaticm, hut the strategy wall work as desired even if this 
problem is repaired in a subsequent version of AppleScript 
Studio. We will save our preference item to a disk file 
immediately after it is changed by the user and retrieve it from 
disk whenever it is needed. Rvery titne the application is 
launched, it will look for a preferences file in a standard location. 
If it does not find the file there, it will immediately create a new 
one, setting its contents to initial default values coded into the 
applicaticm. If it does find a preferences file, it will use the 
settings found in it, even if the settings it used the last time it was 
HJn w^ere different (for example, the user might have substituted 
a new preferences file for the old file in the meantime). 

This strategy will be implemented in a new script, 
PreferencesModel.applescript. The script will include several 
handlers for opening tlie preferences file, closing it, setting its 
initial default values if the file does myi already exist, and 
retrieving all of its values. In addition, it will include, for the one 
preference item implemented in this article, a “get” and a “set" 
handler to retrieve or change its value. Additional get and set 
primitives can be added later, if additional preference items are 
needed. Tliese are termed "primitive” handlers, because they get 
dowm and dirty with the underlying details of our preferences 
system. Later, we will call these primitive handlers from higher 
level handlers implemented in the PreferencesController.applescript, 
to interact w ith the user. 


We will .set the initial, or default, value of our one 
preference item to true in a permanent property, 
preferencesDefaultRec, to match the selected state of the 
checkbox that we created earlier in the Preferences wandowi 
The property holds an AppleScript record, and additional 
labeled fields can be added to it if additional preference items 
are needed. This default value will be used whenever the 
application can't find a preferences file. Strictly speaking, it 
w^asn’t necessary to select the checkbox in Interface Builder, as 
we did above, because the application will get the default setting 
from this property in any event and update the checkbox to 
match. The property that holds the default preference item value 
w ill never be changed by our code, so it will be initialized to the 
original default value every time the application is launched, and 
the tack of persistent property changes in this release of 
AppleScript Studio won't matter. If we change the default, we 
will recompile PreferencesModel.applescript, and its new value 
will thereafter remain as is until we again recompile. 

As described abtwe, we will provide primitive handlers in 
PreferencesModeLapplescript to initialize and to get and set the 
values of this property on di.sk. These handlers are intended to 
be called from an()ther script in the application, 
PreferencesController.applescnpt. However, handlers in another 
script cannot he called directly in AppleScript Studio, Instead, 
we have to resort to a simple .strategy of indirection. We place 
each of them inside an explicit .script object defined in 
PreferencesModel.applescript using AppleScript's Script keyword. 
In fact, the entire body of PreferencesModeLapplescript is 
enclosed in a .script object, named preferencesModelUb, Any 
other script in our applicatiem that needs to call one of these 
handlers will use the Load Script command from the Standard 
Additions scripting addition to load a copy of 
PreferencesModel.applescript and store its script object, 
preferencesModelUb, into a property, p refs Mode I Lib, declared in 
the calling script. 'Phen the handlers of the loaded script object 
can be called by telling the properry in the calling script to 
execute any of them. 

Declaring a script object within a script, as we have done 
here, is sometimes required in AppleScript, for technical reasons 
having to do with the context within w hich the script's handlers 
are to lie compiled and executed. For a detailed explanation, 
read the Script Objects chapter of the AppleScript Language 
Ckiide and a short article I wrote far The AppleScript 
Stjureebook, Suhrouluw Handlers in Script Lihraries and Script 
5mm, at vvww.applesaiptsoarcebook.com/tips/scrEptserverhtnril. 

To create the new' script, .select the Preferences window in 
Interface Builtler and go to the AppleScript pane of the 
N.SWindow' Info panel. Click the New Scrip! button at the bottom 
and save it as PreferencesModel.applescript in the Doyle project, 
New^ AppleScript scripts can be created in this manner in 
Interface Builder or, as we will see later, in Project Builder. 

Now switch to Project Builder, where you will see the new^ 
PreferencesModeLapplescript file in the Scripts group. Select it, 
and, In the editing pane of the project window , type tlie script 
object and handlers shown in Listing 1. In AppleScript jargon, 
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this file is allied a "script library.” The use of script libraries is a 
common, if somewhat advanced, technique in AppleScript 
generally. A script library functions much like an "include” file, 
allowing properties, handlers and other AppleScript constructs 
declared in one file to be used in anotlier file tlirough 
AppleScript's Load Script mechanism. 

Listing 1: PreferencesModel.applescript 

(" Prtfcantx'^Model.^ippkscript •> 

(’This is an MVC Mixlel script that managt^s the rallies of preference settings. It 
provides an iniiialiyaiticin trandkr fiir al] of them imd get and set accessors for each, as 
well as some utUity JiandJers. *) 

C Initial ddanJi values are set in the initPreferencesQ handler, which is cxectned only 
if no preferences file i.s fi:iiind at launch . Otherwise, the values of all preferences are 
obtained from the preferences fde.A preferences file is saved in tlie cnrreni user’s 
Prefeicnces folder at -/IJbrary/Preferenecs Tire file is always dosed inimetliately after 
reading or writing in order to avoid corruptkin in the event of a crash. Preferences are 
saved and managed as a single AppleScript reeorxl. Error cheeking is omitted. *) 

C Ptt^periies *} 

” Name of preferences file 

property preferencesFileName : “Doyle Preferences" 

" Definili preference record; this property may not be changed by a user, s<j it serv'es 

— as a permanent record of default rallies for initialization of new preferences files 
property prefecencesDefaultR.eC : [ showCommentsPref: t cuel 

— Insen other fields in the preferencesDefaultRec record with comma delimiters 
“ if additional preferences are added, and recompile, 

(• Script Obiects *) 

script preferencesMadgiLib 

(- Handlers ’) 

— Tlicse liandlers provide access to preferences at the most primitive level. 

— Um\ this script object into anotlier script and call Uiese primitive handlers 

— wdurever access to prefeamces is ret|uirid Jf the preferences infrastrnctnre 

— is later changed, only this script wili require revision, so long as ihe 

— names and return values of Uiese liandlers remain unchanged. 

an opetiPreferences{) 

— Opens current user’s preferences fife, creating an empty file if none exists. 

— Returns path current user’s preferences file for use in other handlers, 
set preferencesFilePath to 

{path to preferences from user domain as string) ^ 

^1 preferencesFileNsime 

open for access file preferenceaFllePath “i 
with write petTnlssion 
return prefereneosFilePath 
end openPreference^ 

on closePreferencesO 

— (Hoses current user’s preferences file, saving ehanges. 
set pceferEncesFilePath to 

(path to preferences from user domain as string) ~f 
Si preferencesFlleName 
close access file preferencesFilePath 
end closePreferences 

on InitPreferences{) 

— Sets preferences to default value.^ If no preferences file exists, 
set preferencesFiiePath to openPreferencesf) 
try 

read file preferencesFilePath 

— discard if succcssfel 
on error mtinber -39 

— end of file indicates file Ls empiy (just created) 
write preferencesDefaultRec to 

file preferencesFiloPath as record 
end try 

closePreferencesO 
end initPreferences 


on getPreferencesRecordO 

— Rciums the entire current preferences record. 

set preferencesFilePath to openPreferences() 

set thePreferencesRec to ^ 

read file preferencesFilePath as record 
closePreferences() 
return thePreferencesRec 
end getPreferencesRecord 

on get ShowCotnment sPreference [) 

— Returns current value of show cumnicnts preference item, 
set thePreferencesRec to getPreferencesRecord() 
return showConmientsPref of thePreferencesRec 
end getShowComraentsPreference 

on setShowCottmtentsPreference (setting) 

— Sets new value of show comments preference item, 
set preferencesFilePath to openPreferences[) 
set thePreferencesRec to “> 

read tile prsferencesFiloFath as record 
set showCoarmentsPref of thePreferencesRec to setting 
set eof file preferencesFilePath to 0 
— discard old contems of file 
write thePreferencesRec to 

file pteferencesFilePath as record 
closePreferencesO 
end setShowComnientsPreference 

— Insert additkmal accessors on pattern of BetShowCojmientsPreference(J and 

— secS'h(m (kminicnisPrefercncc(seiting) here if additional preferences are added. 

end scrip] 

The odd chameter at the ends of .some lines in Usting 1 is 
AppleScript's line continuation character, allowing us to split 
long lines into shoiter segments so they don't run off the page 
to the right. In most script editors, it is possible to ri^pe the line 
continuation character and start a new line in one stroke by 
pressing Option-Return. In this release of AppleScript Studio, 
however, you must type Option-L follow^ed by Return. We do 
this only to format the .scripts for publication; Project Builder 
incorporates automatic wordwTap without requiring the line 
continuation character. 

After you have ty ped the body of PreferencesModel.applBScript, 
examine each of its handlers. These are garden-variety AppleScript 
statemenLs, using the l^ead.-Write commands in the StandartJ 
Additions scripting addition. If you aren't familiar witli them, you 
can read about them in Apple's Scripting AcidUiom Gaidit or any 
of the .several good liooks a bom AppleScript currently in print. 

Updating the User Interface 

Next, w^e need to WTite the PreterencesConlrollerapplescript 
.script that w'ill call the primitive handlers in 
PreferencesModel.applescript to get and set the preference item’s 
value, display it in the Preferences wandow, and accept changes 
made by the user. 

To carry out the ModehView-Controller (MVC) paradigm 
consistently, we will use this new script to hold the handlers that 
coordinate the user interface of the Preferences window with the 
value of the preference item, As its name indicates, it is a 
Controller, the third component of the MVC trinity. The second 
component, tlie View, is essentially already WTirten, in that 
AppleScript Studio comes w'ith many predefined view classes, 
such as windows and user controls, with built-in event handlers 
to take care of their basic functionality. By putting handlers that 
control tlie stare of the various View' objects into a separate 
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Controller script, we effectively isolate the View from the Data. 
The Controller serves as an iniennecliary bem^een the Model and 
the View and therefore must know about Ixith of them. 
PreferencesModeLapplescript. which is the Model holding the 
preference system's handlers for accessing the data, knows 
nothing about the nature or features of the user interlace (the 
View), and the huilt-m Cocoa View objects know nothing about 
the structure and implementation of the data they represent (the 
Model). For thai reason, PreferencesModeLapplescript need not 
be changed in any way even if we completely revise the user 
interface. Only the Controller script will need to be customized 
if the user interface is changed. 

Go into Project Builder now and create the new script. 
Choose File -> New File, then in the New File assistant select 
AppleScript File under the AppIeScnpL heading and click Next. 
In the New AppleScript File assistant, name it 
PreferencesController.applescript and click the Finish button, first 
making sure that the location is set to the Doyle project folder, 
if the new file appears elsewhere in the Group.s ^ Files pane of 
die project window, drag it into the Script.s group. Type the 
property and script object shown in Listing 2 into 
PreferencesController.applescript. 

listing 2: PreferencesCx)ntrolIenapplescript 


OSX Caiifon 
Mac OS 7.1-9.x 
Windows 95-2000 



ColendarMonster i .2 

Multi'■platform calendar 



C PrefcrencesConiroUer.appIt^cripi *) 

CThls is m MVC Controller script that contains handlers to coordinate data values in 
Pit?feia:ncesM{xiL-l.appk*script with the user interCace in the Preferences wlruJow, *) 

{• Properties *) 

pcopEtty prefaModelLib ; null 
(* Script i)hjecLs *) 

se rIpt prnfnrencesCont rolie rLib 
C Handlers *) 

—lliese handlers get and set preferenceiv using plain English terminology, by 

— loading and calling the primitive liandlers in PrefciencesMtjdel.applescript. 

— [f the preferences infrastructure in PrefereneeiiModeLappiescripi is later 

— changed, this script will not require revision, so long as the names and 

— return values of ihc primitive ImdJcrs remain undiangcd. 

on initPrefsC) 

load? ref erencesModelLibO 
tell prefsModelLib to inltPreferences0 
end initPrefs 

on CDinineiitsAreSliDwn () 

loadPreferencesModelLibO 
tell prefsHodelLib to 

return getShowCocmieTitEPreference () 
end commentBAreShown 

on ahowCoimnentsO 

loadPreferencesMod elLib() 

tell prefsHodelLib to setShowCoramentsPreferenceCtrue) 
end showCoiMients 

on hideCoicmentsC) 

loadPreferencesModelLlb t) 

tell ptefsModelLib to setSbowCcnrrtiieiitsPreference(false) 
end bideComments 

end script 

{* Handlers *) 
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on loadPreferenc^sHodelLibO 

— Loads Prcfcrt^ncesModelLib fjxjm Pa^fcrencesModclappIcscript. if ntjt liradcd. 
if class of prefsHodelLib is not script then 
load script POSIX file ^ 

((patb for script '^PreferencesHodel" ^ 
extension "sept**} of tnain bundle) 
set prefsModelLib to preferencesModelLlb of result 
end if 

end loadPreferencesModelLib 
(* Event Handlers *) 

— See listinj^ 5,6, ;Lnd 7 for the event handlers in this script. 

The AppleScripi handlers that are enclosed in an explicit 
script object named preferencesControllerLib in 
PreferencesControHer.applescript are the high-level handters we 
referred to above. Their names implement English-like grammar 
intended to facilitate their use in simple statements thai sound 
very like normal English sentences. Each of them first loads the 
script object in PreferencesModel.applescript. if it is not already 
loaded, and then calls the primitive methods implemenied there. 
The high-level handlers are placed in a script object in 
PreferencesController.applescript so iliai they, in turn, can be 
loaded and called by other scripts in the application, as we will 
see later While this double layering of handlers is not neee.ssary 
in an AppIeScripi Studio appljcalion, it is used here as pari of 
our effort to separate the Model t)bject from the View in 
acasrdance with the MVC paradigni. It echoes a technique 
commonly used in Cocoa applications. 

Outside of the PreferencesControHerLib script object. 
PreferencesController.applescript implements one proj^ert}- and one 
handler The property, prefsModelUb, wail hold the 
preferencesModelLib script object from PreferencesModei.applescript. 
It is assigned that value by the handler, loadPreferenceslVIcxielLib(). 
using the Load Script command from the Standard Additions 
scripting addition. 

I'he loadPreferencesModelLibO handler uses a common 
AppleScript technique to loud the script library only when 
loading is needed. It first tests the prefsModelLib property to see 
whether it is of the built-in AppleScript class, Script. If it is, we 
know- that the script library' has already been loaded, because 
the prefsModelLib propeny was initially set to null in its 
declaration. This technique takes advantage of the fact that 
AppleScript properties and variables are not strongly typed; their 
type is the type of whatever value they currently hold. 
Therefore, w'e can call die loadPreferencesModelLibO handler in 
every' handler that gets or sets a preferences value, knowing that 
the call will do nothing if the script is already loaded, in order 
to ensure that the script wall always be k)aded when neces.saryc 
As a bonus, if projierties retain their values across relaunches of 
an application in a future version of AppleScript Studio, the 
script library^ will only have to be loaded the first time the 
application is run after it has been compiled or recompiled. (The 
modest execution efficiency this gives us on subsequent 
launches comes at the expense of some increa.se in file size. If 
this is an issue for your application because its preference 


.settings are very^ large, you can reset the prefsModelLib property 
to null wdien quitting the application). 

The file holding the PreferencesModei.applescript .script mmst, 
of course, be found before it can be loaded in this manner. We 
know from the AppleScript Studio documentatitm and from 
examining built examples that the script files contained in an 
AppleScript Studio application bundle are located in a Scripts 
subfolder in the Resources folder in the application bundle’s 
Contents folder. One w'ay to find these script.s, therefore, is to 
code this path explicitly into a handler The only other thing w^e 
need to know' is the path to the running application, which can 
be obtained from the Standard Additions’ Path To jVle command. 
Also, the script's file extension will change from ^applescript" in 
its text form to ".sept" in its compiled form. The 
pathToPreferencesO handler in Listing 3, using this technique, is 
cribbed in part from several of the AppleScript Studio examples. 

listing 3 

Qf\ pathToFreferencesHodel () 

Bet appPath to [path to me from user domain) as text 
return (appPath & "Contents:Resources[Scripts:'0 as text 
end pathToPrafereficesModel 

on loadPreferencesModelLib[) 

if class of prefsModelLib is not script then 
set prefsModelLih to load script file 
(ttiy pathToPreferencesModel () it 
"PreferencesModel.sept") 

end if 

end loadPreferGncesModelLib 

There is a mtjre flexible means to accomplLsh the same end, 
however, using special features in AppleScript Studio's 
diciionaiy. The Application Suite in AppleScnptKit.asdictionary 
includes a Path For event that returns the path U) any of several 
special AppleScript Studio locations, including the location of a 
script in the application bimdie given its name and its compiled 
file extension. Similar features are provided in the Bundle class, 
wiiose properties provide the paths to important cc^mponents of 
an application bundle. Here, we use Path For in conjunction with 
tlie application object's Main Bundle property, which wall 
hopefully give our application a more robust capability to 
survive any future changes to the location in wiiich scripts are 
bundled in some future version of AppleScript Studio, 

There is a w rinkle to using the Path For event and the similar 
class properties: they return folder and file paths using the 
forw^ard slash character as a delimiter, as required by Cocoa, 
w'hereas most AppleScript commands, .such as the Load Script 
command in Standard Additions, require the colon character as 
a delimiter. Fortunately, AppleScript 1.8, included with the first 
release of AppleScript Studio, contains a new POSIX File class 
and a POSIX Path property to make it easy to convert file paths 
between the slash-delimited POSIX form and the colon^ 
delimited AppleScript form. 

A srep-by-step version of our loadPreferencesModelLibO handler 
using the POSIX Path property is set fortli in Listing 4. Note that the 
Path For Script command takes a second parameter, Extension, 
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which is not documented in the initial AppleScript Studio manual 
or the AppleScriptK(t,asdictionary. iLs usage can be gleaned from one 
of the exaETiples; using path for script “Preferences^scpt" will not w^ork. 
Note also that we do not have to bracket Main Bundle in a Tell 
Application block, because this is assumed in AppleScript Studio, 
(The final version of our loadPreferencesModei() handler, 
telescoping the first tliree lines of the If clause in Listing 4 into a 
single statement, can be seen in Listing 2.) 

listing 4 

on loadPreferencesModelLibO 

if class of prefsModelLib is not script then 
get (path for script ^PreferencefiModel" ^ 
extension -sept”) of main bundle 
get POSIX file result 
load script result 

set prefsModelLib to preferencesKodelLlb of result 
end if 

end ioadPreferencGBModelLib 


Connecting Event Handlers 

As written lu this point, txur scripts will do nothing, because 
none of the handlers w'e have written has yet been “connected" 
to an AppleScript Studio event handler This is a fundamental 
lesson to be learned in writing AppleScript Studio applications. 
No AppleScript handlers will be executed unless they are either 
directly connected to an AppleScript Studio event handier using 
the AppleScript pane in the Interface Builder Info panel, nr 
unless they are called (directly or indirectly) from a hantlier that 
is connected to an event handler in this manner. This is why, for 
example, a Run or Reopen handler in an AppleScript Sutdio 
script will never be called, even though it will compile lieeause 
these events are proper AppleScript syntax: iliere is no Run or 
Reopen event in AppleScript Studio, so we can t connect them. 

Event handlers are connected using Interface Builder. 
Befixre switching to Interface Builder tt) do this, ht>wever. we 
must first save our project in Project Builder. Due to the way the 
first release of AppleScript Studio is set Lip, lliere Ls a risk that 
we will lose most or all of our scripts if they aren’t saved before 
switching to Interface Builder and connecting new event 
handlers. Therefore, compile and save the project now. Ill is 
problem is fixed in AppleScript .Studio i.l. 

The first event handler we will connect is Choose Menu Item 
in MainMenu.nib. The user of Dtxyle must have some means of 
opening our Preferences window in order to review and set 
preferences, and in Mac OS X this is normally done by c hoosing 
the Preferences menu item in the Applicati{)n nienm In Interface 
Builder, open MainMenu.nib and, if necessary, doubie-click the 
MainMenu icon in the Instances pane to open the menu bar. 
Click the Application menu on the left to open it, and .see that it 
contains a Preferences menu item. If we were to compile and 
run the application now, we would find that this menu item Ls 
disabled. In order to enable it, we will have to connect an event 
handler to it. Click on the Preferences menu item to select it, 
then, in tlie AppleScript pane of the NSMenultem Info panel. 


click Choose Menu Item under the Menu group in the Event 
Handlers area, click PreferencesControllerapplescript in the Script 
area at the bottom, and click the Edit Script button. A new 
Choose Menu Item event handler appears in 
PreferencesControllerapplescript in Project Builder. Fill in the new 
event handler with the statements shown in Listing 5 (the 
ellipsis, or three dots, are typed by pressing Option*; ). 

Listing 5 

on choose menu item theMenuItem 

if title of theHenuItem is “Preferences...” then 

load nib "Preferences'" 
end if 

end choose menu item 

Altlicugh not necessary at this point, we enclose the Load 
Nib command in an If block checking the name of the menu 
item. This will make it ea.sier to connect Luher Choose Menu Item 
event handlers in this script in the future, if desired. AppleScript 
does nor allow overloading of handlers .so scripts cannot 
contain multiple handlers having the same name, even if the 
direct parameters differ. Being limited to a single Choose Menu 
Item event handler in any one script, we have to test the 
parameter in chained [f/Else clauses to find the one menu item 
that the user chose. 

This event handler causes the Preferencesmib file to be 
loaded (notice that the ".mb'* file extension is omitted), which 
will cause the window that we designed in Interface Builder to 
open. How'ever, it will open invisibly, so we will have to tell it 
to become visiiile after the nib file has been loaded. 
Furthei iiKire, we should set the visual .state of its user controls 
to match the state of the preferences file Ixefore making it visible, 
in order to avoid unsightly flashing. AppleScript Studio invokes 
a Will Open event handler whenever a window is about to open, 
so we will connect that event handler next. (In AppleScript 
Studio 1.1, it is preferable to use the new Awake From Nib event 
handler in the Nib group; the behavior of Will Open w ill change 
in future updates.) 

Before sw itching to Interface Builder, save the project file to 
ensure that our scripts will not be lost. In Interface Builder, open 
Preferencesnib and, if necessary, double-click the Window^ icon 
in the Instances pane to open the Preferences w4ntk)w. Click in 
an empt)' area t>f the Preferences window to select it if 
something else is currently selected. Then, in the AppleScript 
pane of tlie NSWindow Info panel, click Will Open under the 
Window group in the Event Handlers area, click 
ITeferencesControlier.applescript in the Script area at the 
bottom, and dick tlie Edit Script button. A new' Will Open event 
handler appears in PreferencesControllerapplescript. Fill in the 
new' event handler w'ith the statements show n in Listing 6. 

Listing 6 

on vill open theWindow 

if title of theWindov Is "Preferences'' then 
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set state of buttan 1 of theWindow i 

to preferencesControllerLib’E commentsAreShovnO 
set visible of tbeiJindow to true 
end if 

end will open 

This is the first time we have called a handler that resides 
in a script object. Here, we do so by qualifying the call w ith the 
possessive form of the script object’s name, 
preferencesControllerLtb'S; we could as w'ell have used 
AppleSaipt’s alternative syntax, of preferencesControllerLib, or a 
tell prGferBncesControllGrLib block. The single checkbox in the 
Preferences window is button 1 of that window' (in Cocoa, a 
checkbox Ls implemented as a form of button), and we w'anr to 
set its State property to checked or unchecked, according to the 
cuiTent value of the preference setting. Tlie preference setting 
is saved as a true or false value in AppleScript terms. Although 
the Cocoa documentation tells us that a checkbox button’s State 
value is an integer, capable of taking any of the values 1, 0, or 
-1, Cocoa allow^s 1 and 0 to be represented, respectively, as YES 
or NO (true or false). (In Cocoa, -1, or the constant 
NSMixedSlate, represents a mixed-state checkbox, portrayed 
with a dash in the checkbox instead of a checkmark.) We 
therefore get the return value of the commentsAreShownO 
handler in the preferencesControtlerLib script object and set the 
State of the checkLiox to the returned Boolean value, Since the 
script object is both declared within and called from 
PreferencesController.applescript, it isn't necessaiy to use the 
Load Script command to k^ad it. 

We know, from the work we have done so far, that invoking 
the commentsAreShownO handler causes 

PreferencesController.applescript to load the prGferGncesModelLib 
script object in P ref e fences Mode l.applGscrtpt into the PrefsModelLib 
properly, if it isn’t already loaded, and to tell the PrefsModelLib 
property to execute its GetShowCommentsPreferenceO primitive 
handier, and that the latter in turn reads the preferences file from 
disk, pulls out the value of the desired preference item, and 
returns it. All of this happens in a trice. Then, w'hen the Visible 
property of the w'ind{)W' is set to true, the window appears on 
screen, with a checkmark in the checkbox if the preference value 
on disk w'as true. 

The final event handler needed liy 
PreferencesController.applascript is a Clicked handler to update the 
value of the preference on disk w^hen the user clicks the 
checki>ox. Cocoa auitjmatically supplies the checkmark w'hen 
the user clicks. With Preferences.nib still open in Interface 
Builder, click on the checkbox to select it, then go to the 
AppleScript pane of the NSButton Info panel. In the Action 
group, check the Clicked event handler, and check the 
PreferencesController.applescripl script near the bottom, then 
click the Edit Script button. In Project Builder, fill in the new 
Clicked handler according to Listing 7. 

Listing 7 

on tlidsed theControl 

If title of theCojittol is 

‘"Show Comments in Usage Log" then 


if state of theControl is 1 then 

tell preferencesControllerLih to showGomments() 
else 

tell preferencesControllerLlb to hldeComffletitsC) 
end if 
end if 
clicked 

By now, you can trace out for yourself exactly how this 
works. We assume that, if the state of the checkbox is not 1 
(true), then it must be 0 (false), because w^e do not make use of 
the available third state of a Cocoa checkbox in Doyle, 

There is still one important thing missing from our 
preferences system: the preference file doe.sn't gel initialized to 
default values if no preferences file is found when tlie 
application is launched. We want our preferences to l?e 
initialized as soon as the application has finished launching, so 
an appropriate event handler to connect is the Will Finish 
Launching event handler in the Application Suite. This is 
equivalent to Cocoa's awakeFromNlb method. It is invoked by the 
system after the application's nib files have been loaded, the 
user interface has been initialized, and other Cocoa initialization 
has taken place. 

The MainMenu.nib file Ls the main nib file for the application, 
and the File’s Ow^ner of that nib file is Cocoa’s NSApplication 
class, .so this Ls where to connect the Will Finish Launching event 
handler In Interface Builder, open MainMenu.nib, click the File's 
Owner icon in the Instances pane to select it, and open the 
,\ppleScript pane of the File's Owmer Info panel. Expand the 
Application group and click to select the checkbox beside tlie 
Will Finish Diunching event handler. Then click to select 
Application,applescript at the bottom of the File’s Owmer Into 
panel, and click the Edit Script button. 

When you .switch back to Project Builder, you wall find that 
a Will Finish Launching handler has been added to 
Application.applescript. The Application.applescript script was 
supplied by the AppleScript Document-based Application 
template when we first created the project, hut it was empty. 
Type to fill in the statements in the new' Will Finish Launching 
handier as show n in Listing 8. 

Listing 8: Application.appiescript 

(’Appliotitjn.appJestript 
r PrDptTliefi 0 

property prefECoiitrollerLib : null 
{* HandlLTs p 

on loadPreferencesGontrollerLlb{) 

— U)=kU PrcfcrtnctJsCctnm^lItrlib from PreferencesComroUcrappicscript, it not 
loaded. 

if class of prefsControllerLib is not script then 
load script POSIX file ^ 

{{patb for script "PreferencesController'' 
extension "sept") of main bundle) 
set prefsControllerLib to ^ 

preferencesControlierLib of result 
end if 

end loadPreferencesControllerLib 
(‘ Event hatidters *} 


58 


Ai*pleScript Studio 


MAtlTEcii • May 2002 





on will finish launching theObject 

— Initializes the application sifter main nib files are loaded and initialiited by Cocoa. 

— Ctmrtectcd to Rle’s Owner in Main Menu, nib 

— Initialize preferences to default \'aJues, If preferences file not found 

loadPreferencesGontroilerLih() 

tell prefsControllerLlb to initPrefs{} 
end will finish launching 

You know from earlier work wliai chain of events this event 
handler unleashes. 

Notice, however, that this is the first time we have called a 
method m PreferencesController.applescript from outside of that 
script, in this case, from Application.applescrlpt, We therefore 
needed a handler to load the preferencesControllerLib script 
object from PreferencesControllerapplescript into a property in 
Applicatlon.applescript. We did this the same w-ay w^e loaded a 
script property from PreferencesModel.applescript into 
PreferencesController.applescript, The necessary property and 
handler are shown in Listing 8. 

Until Next Time 

This installment is now^ complete. We have a working 
preferences system for Doyle. 

To check it out, first compile [>oyle for deployment. In 
Project Builder, open the Targets pane by clicking the Targets tab. 
In the Build Styles area at the bottom, select the Deployment 
radio button, then rebuild the application. In the Finder, open the 
Build subfolder in the Doyle project folder, and drag a copy of 


the Doyle application into your Applic'ations folder. Double-click 
it to launch Doyle and see its main w indow^ open. Then choose 
Doyle -> Preferences and see the Preferences window' open. If 
tills is the first time you have run Doyle, there was no Doyle 
Preferences file in existence, so you should see that the button is 
checked to reflect the default value of the preference. Uncheck it 
and close the Preferences window. Reopen the Preferences 
window, and you will again see it unchecked, proving that it 
successfully wrote the new' (^reference value to disk and retrieved 
it. You can even quit and relaunch Doyle and perform the test 
again, if you doivt believe it. 

In the next installment, we will write the necessary' scripts 
to make the Doyle Usage Log work, and to save and retrieve its 
values in an AppleScript Studio document. We will, of course, 
u.se our new preferences system to determine whether the 
Comments column in the Log window should be shown. 

In addition, we w'ill use the next mstaUnient to fix a hug in 
our application, Did you find the bug while you were testing 
Doyle a mfiment ago? No? Well, try this: Launch Doyle, choose 
Doyle -> Preferences, and then choose Doyle -> Preferences 
again. The screen looks right, but try^ dragging the Preferences 
window' to a new location. Oh, no! — there are two Preferences 
windows. A quick kxik at our code reveals tlie reason: We 
reload the Preferences.nib file every time the user chooses the 
Preferences command. Your challenge is to fix this bug with as 
little new code as possible, before we reveal our bug fix in the 
next installment. 
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APPLESCRIPT 
IM COCOA 


Don Briggs <donbriggs@mac.com> 

It’s Now Easier to Support AppleScript 
Suites in Cocoa 


AppleScript Studio is now available to developers. This 
product will open Mac OS X development to many more 
people, and they will build applications relying on 
AppleScript. If their applications are to interoperate with 
yours, your Cocoa applications and their underlying 
frameworks must also support AppleScript, 

This article is for Cocoa Objeettve-C developers. It will 
review the concepts and techniques necessary to implement 
AppleScript support. It will show' the steps necessary' to revise an 
existing example to support AppleScript. It introduces a new 
application for composing AppleScript suites —-SuiteModeler. A 
compressed disk image 

EZCocoaAppleScript.dmg.gz is availalile for download at; 
http;//homepage.macxonn/donbriggs/FileShanng.html 
The disk image contains; 

• this document as EZCocoaAppleScript.rlfd; 

• KVC_Demo —simple Project Builder tool project that 
demt>nstrates Key-Value Coding; 

• DotSuite.scriptDocument, a SuiieModeler document (a 
wrapper/directory) containing 

the suite definitioji and suite terminology files for a Cocoa 
AppleScript suite, and 

a directory of ‘naive* Objective-C files to support the suite. 

• SaiptableDotView' —the example application we will build 
in this article as a Project Builder project; 

• sample output documents (bigRedxloi, little Blue,dot) in XMI, 
form; and 

• a test script that drives our ScriptabieDotView' application, 

OVI-RVIEW 

In this article, we wall compose an AppleScript suite from 
SQ'atch using SuiteModeler This suite will serve as a statement 
of requirements, and the Ohjective-C files that SuiteModeler 
emits w'ill serve as a starting point for our implementation, 
From these Objective-C files we will implement the classes and 
commands of the .suite. We wall build the document-based 
application, ScriptableDotView, that supports the suite. To 
emphasize KVC, we will also employ it to provide XML 
persistence for our documents in just a few lines of code. We 
w'ill repackage the datadiandling classes of our suite as a 
reusable framework. Finally, w'c will test our implementation 
using AppleScript. 


Introddceng SuiteModeler 

The reader is invited to download SuiteModeler version 
1,7,2 (or later) and run it in Demo mode. You need not buy 
a license to follow this article —the disk image provides all 
the required output files. SuiteModeleris Demo mode also 
permits you to inspect otlier suites and to check them for 
coni'!icts (see below). In licensed mode, SuiteModeler will 
save the suites you compose. 

SlTTTES WTiRE HARD TO COMPOSE 

Nominally we use Apple's “PropeityLisi Editor"* application 
file:///Developer/Appltcations/PropertyListEditor.app 
tt> compose CtK’{>a suites. It supports the property list 
format, but the fcdlownng difficulties remain: 

We need to produce two files, the ’.suiteScript and 
VscriptTerminology. Each provides its own “projection** of die 
underlying classes, but these projections are not “orthogunar— 
the two files must maintain a nontrivial correspondence. But 
“FropeityList Editor' edits each file separately, 

'Fhere are lots of key w^ords, and their values must obey 
rules. You must read and apply 

file:///Developer/Documentation/Cocoa/ProgrannrTiingTopiG/Scripting 
Some symbols refer to others, but unresolved references are 
not immediately obvious. 

There are some annoying or confusing aspects of the Cocoa 
documentation: we find iw^o meanings for the word ”Property,” 
for instance. 

Some entries are generic and could be "calculated” from 
others, but “PropeilyList Editor” does not provide such help — 
it's a genertil application. 

Finally, when inspecting a suite (or rather, one half of a 
suite) in “PropertyList Editor,” much of the text w e see amounts 
to repeated key w'ords. 

In short, we could use some better tooling. 

Suites were Hard to Support 

Given a composed .suite, the developer hoping to support 
AppleScript in Cocoa must make sure the Objective-C classes 
correspond to the suite. In die plirase often used by College-level 
Math texts, the process is “tedious but straight-forward." And “by 
inspection’* —diose same texts also say “by inspection" a lot. 
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Admittedlyj your second suite will he much easier, your first 
one will require close reading of several lengthy documents. 
Wouldn’t it he nice if your first suite were easy and it “just 
worked? 

Suites were Hard to Debug —Confucts! 

Even after a script compiles, it may not mn as expected; the 
trouble often lies in the relationships of Apple Event Codes and 
external names, A given code can asscK'iate with multiple 
external names, but a given external name must associate with 
a unique code. If your suite matches an Apple Event Code with 
an external name that already exists in another suite loaded at 
mn-tiiiie (NSCoreSuite and NSTextSuite come to mind), scripts 
written against your suite may crasli or yield unexpected results. 
Such conflicts have stumped experts —and for good reason. To 
the author's present knowledge, this “gotcha” remains 
undocumented by Apple. (Greg Titus of OmniGroup for pointed 
our this “gotcha” to the author. Thanks, Greg.) 

Composing and Supporting Cocoa Suites Just Got Easier 

SuiteModeler is available as a demo at 
http://homepagG.mac.com/donbriggs/FileShanng.html 
You arc invited to download il and llsc it to inspect Ct>coa 
suites. The dovvnload site pnjvides a screenshot of the suite from 
the Create application from Stone Design, 

The Cocoa suites yoii compose will often build on 
NSCoreSuite and NSTextSuite, You’ll find these among 
Suite Modeler's “Open Recent” menu items, Wlien using 
SuiteModeler to tasped a suite or check one for con 11 ids, !>e 
sure to open any suites it depends on. 

Background on AppleScript in CtK:oA 
To implement AppleScript support in Cocoa, you need to 
know about two important supporting concepts —the design 
pattern known as ModebView-Controller (MVC), and the 
technique known as Key-Value Coding (KVC). If you have not 
seen these Cocoa documents liefore, 

file:///Developer/Documentation/Cocoa/Progr3mnningTopics/AppDesi 
gn/AppDesign. 1.html 

ftle:///Developer/Documentation/Cocoa/TasksAndConcepts/Program 

mingTopics/KeyValueCoding/index,html 

this article will introduce you to the main ideas we need to 
understand to support AppleScripL We also need to focus on 
document-based applicalitms as described in 

file:///Developer/Documentation/Cocoa/ProgrammingTopics/AppDesi 
gn/AppDesign,dhtml 

You wall find that when we use NSApplication and 
NSDocument. w^e get lots of AppleScript support for free. 

Regular readers of MacTech and those long interested in 


AppleScript for Cocoa already know' of Andrew^ Stone's earlier 
anicle, “Adding AppleScript Support to Cocoa Apps.” 

http://www.mactech.com/artides/mactech/Vol.16/16.07/AppleScriptt 

oCocoa/ 

There, Andrew' discu.ssed MVC, KVC, and AppleScript 
support in the Sketch example. Andrew's article also showed us 
how^ to add a “Save as AppleScript...” capability to Sketch. 

Sketch is quite a large example, and presents its AppleScript 
.suite with little explanation, A reader previously unfamiliar with 
Sketch might find it daunting. This article takes a bare-bones 
approach to building a suite —the ratio of explanation to code 
is quite different. We start from a simpler example, DotView, 
w'hich is found at file:///Developer/Examples/AppKlt/DotVlew. 

Newcomers might compare DotView and Sketch for size 
and complexity, then take a relaxing deep breath. 

Model-View-Controller —MVC 

I’he Model-View-Controller design pattern comes to us from 
the Smalltalk tradition. MVC SLiggests that we partition our 
objects into thcjse that treat the “real data” —the “Model” part; 
tiiosc that provide a human interface to the data —the “View'”; 
and other stuff necessaiy to gkie tile Model and View' together 
—the “Controller” part. 

Generally, design patterns identify commonly occurring 
archetypes of tnlercjperaling components, They bear “prior 
knowledge” at liie conceptual and architectural level. Tlie main 
benefit of follow ing the MVC design pattern is the reusability of 
the components we liuikl, 

The Cocoa frameworks wore designed to .support MVC. 
Using Cocoa, we find we can often make the “Model” part into 
a stand-alone framework and u,se it again for other purposes. 
Our “Model” framew'orks commonly liuikl on the Foundation 
framework —Foundation comprises mostly “Model” classes that 
encapsitlate “real data.” The AppKit framework provides classes 
that support the “View” and “Controller” parts. Often, we can get 
most or all tlie “View” pan from Interface Builder, For 
ScriptalileDotView, Coc<ja provides much of the Controller part 
with no extra code. If you avoid storing “model" infomiation in 
‘‘viewv” objects (for instance, don't store a boolean in a button’s 
.state), yoLi’li find that ilie Cocoa frameworks provide a natural 
liasis for the MVC design pattern. When we add AppleScript 
capability, we add a powerful way to contnjl the “Model” part. 

Key-Value Coding — KVC 

Key-Value CcKling amounts a simple discipline tliat matches 
the declaration of an tn.siance variable to the declarations of its 
getter and setter methods. When we follow those rules in a class 
for an instance variable, w'e implement KVC in that class for that 
variable. Given an in.stance variable of primitive type ( BOOL, 
char, short, unichar, int, float, double, ,,J or struct (NSRange, 
NSPoint, NSSlze, NSRect, .., ) we have as a declaration 

type _xyz ; // Let t)pe be one of: 

// BOOL, chan short, nnichiin inn floaty double,..., NSPoini, NSS[/c, 
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if NSRect, ...and aii accessors 
-(type}Kys: 

‘(vold}setXy^: (type)xyai 

Given an instance variable that is an object, we have as a 
declaration 

MyClaEs ’'_abc: 
and as accessors 
-{MyClasa*}abc; 

-{void)setAbet (MyClass*}abc: 

You may neglect the underscore prefix in the name of the 
instance variable, but then you should change the name of the 
argument in the corresponding setter method. 

The KVC_Demo project is a simple one-class tool project 
that shows KVC at work. You can use KVC to reduce the 
complexity of your code, independent of AppleScript support. 
The Cocoa documentation on scripting recommends that you 
“define the set of keys each scriptable class supports.” The 
author suggests that you use class methods to provide 
collections of related keys. In KVC_Demo, the class method 
+[ModelClass kvcKeysl provides such an array of keys. 

DotView Revisited 

Copy the example Dt)tView project to a convenient place, 
compile it, run it, and marvel at it. The Dot View example 
application shows us how a subclass of NSView can respond to 
a mouse click with a drawing operation. The project has a single 
class, DotView—pristine simplicity. But with apologies to 
Dot View's aiahor, Professor Ozer*, the author points out that 
DotView does not follow MVC nor does it support KVC. 
Ncwc(.>mers might hreatlie a sigh of relief now. If presently your 
code falls sliort too, you 11 find yourselves in fine company. 

(*A\[ Ozer only professes to be the head of the AppKit —he 
is the only remaining original engineer from the first four that 
w'orked on NeXTSTEP in the late eighties.) 

Consider the class DotView from the perspective of .MVC. Ti 
descends from NSVicev but has instance variables and accessor 
methods for the only ‘'real data ' tjf the application. It's both the 
“View" and the ‘‘Model/ DotView has no need for a “Controller' 
part, then. We ll revise the project along die lines of MVC. 

As for KVC, we see that there are instance variables named 
“color” and “radius” with the acces.sor.s 

(IBAction)setRadius:{id]sender: 

- (iBAction)setColDT:(id)sender; 

But these methtid .signatures do not support KV^C —c?ach 
‘'setter” method .should take as its single argument a varial^le of 
the same type as its associated instance variable. To suppon 
KVC, we need instead 

-{float)radius: 

‘(void)setRadius: (float)radius: 
and 

-{HSColor*)aolor: 

■ (void)setColor: [NSColor*') color: 

We'll fix that. too. 


On to SCRlFrABLEl>OTVlEW..\PP 
Let US imagine that w'e work as developers for the company 
called “My Great Software, Inc.” and that the prototype 
application, DotView, has successfully promoted an idea for a 
marketable application. Marketing loves it. Management is 
committed to it, and now we have to deliver on its promise. 
ScriptableDotView will be our product, an industriahstrength 
revision of the prototype. A high-level meeting has produced a 
set of requirements, (We alw^ays need requirements. How' else 
will we know wlien weVe done?) 

Requirements 

fO] ScriptableDotView reproduces the look and feel of DotView^ 

[1] ScriptableDotView has just one kind of document, and it 
saves the state of a “Dot" —its radius, position, and color. 

[2] The document must persist in KML form. Management loves 
buzz-word compliance. (XML really is useful, though.) 

[31 The document must permit AppleScript access to its dot's 
radius, position, and color. 

[4] llie document must support an AppleScript command, 
ReCenter, to place tlie dot in the center of tlie view area. 

[31 And Marketing suspects that a few other related applications 
could follow t>n, so we shtjuld encapsulate the “real data” in 
a framework that we can use again. 

An iNTERNiVI RE:QtJlREMENT 

The ReCenter command is the .simple.st kind of command; 
it takes no arguments and returns void. While we're exploring 
AppleScript .support, it seems pm dent to demonstrate suppon for 
a command that takes an argument and returns a value, Wei] add 
a command to the Dot class ihal does something simple and 
clearly useless to ScriptableDotView: it will take a string argument 
and return a string with the same characters in the opposite 
order. We 11 spend just a few' minutes under Management’s radar 
on this, but this exercise will improve our confidence in 
.supporting AppleScript. We add to our requirements: 

[61 The Dot class will temporarily support the Rc-verse command 
{a command with one aigument and a return value). 

Design Oveb\iew 

At the core of things, w'e have the concept of the dot, the 
“real data” of the application’—the “Model” in an abstract sen.se. 
We li have a clas,s, Dot, to manage the dot's radius, position, and 
color. Also, w'ell have a subclass of NS Document, 
DotDocument, lo manage a single instance of Dot. The 
separation between the dot and its document may seem 
contrived, but often a document manages a collection of model 
objects, but here, we liave just the single element. (Often, a 
descendent of NSDocument acts as a sort of Model-Controller. 
Contrast this to NSWindowController, wliich is a kind of View- 
Controiier.) As for the rest of the “Controiier” part, we could 
conceivably subclass NSDocumentController and 
NSWindow'Controller, hut for the sake of expediency, we ll force 
into the DotDocument class any leftover model-controller 
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methods we need. Well package the Dot and DotDocument 
classes in a scriptable framework, <Dot>, to provide the “ModeP 
and ^'Controller'' parts of our MVC design. The “View” pan must 
derive from the prototype to preserve its look and feel. Here, 
this means that we can copy the *.nib file of the prototype and 
make a few modifications. As a novel departure, we will start 
with an AppleScript suite as a statement of requirements and 
then drive the implementation to support our suite. 

DotSutte 

Our suite, DotSuite is conceptually very simple: it has two 
classes: an instance of the DtJiDocument class serves as a 
container for an instance of the Dot class. DotDocument has 
just one read-only attribute, its dot Dot has four attributes: 
its X and y positions, its radius and its color. DotSuite has the 
two Commands, but no Enumerations or Synonyms. 

Ideally, Dot should have one attribute of type NSPoint 
instead of two attributes of type float, the x and y positions. 
However, as presently documented, Cocoa AppleScript .suites 
support only primitives (BOOL, short, int, float. .*.) and 
objects as attributes. We look forward to support for .strticts 
such as NSPoint and NSRect. Curiously, if you examine 
NSCoreSuite, youll find a dictionary called ValueTypes with 
one entry pairing the key QDRect with the string value qdrt. 
Also, the NSWindow class has a property named 
boundsAsQDRect and type NSData<QDRect>. As of Mac 
OS 10.1.3, the author has found no documentation 
explaining these entries. We 11 follow the lead of the Sketch 
example and proceed with the pair of iloats (as instances of 
NS Number). 

The AppleScript Suite —DotSuite 

To compose this suite, launch SuiteModeler and edit its 
empty suite document. The screen shots below show^ what to 
type in. In the “Preferences” panel, choose the ''Cocou/E- 
R/FOModeler” nomenclature to see these tab labels. 
SuiteModeler combines the definition and terminology in one 
document and presents It as a tree of table views. Wherever 
a node has multiple children, the children appear as tabs in 
a tab view. The root of the tree, the suite itself, is a special 
case and iippears as a the “Suite” tab among its children. 
Also, an extra “Summary” tab provides a flattened summary, 
useful for sorting out more complicated suites and finding 
conflicts. 

The Suite Itself 

The suite itself has an internal and an external name, an 
Apple Event code, and a description. Fill in these four fields 
as shown. (Throughout this exercise, we will neglect entries 
in the description field.s. SuiteModeler makes it easy to add 
them, and they can be extremely useful to the AppleScript 
authors who will incorporate your application in their scripts. 
However, descriptions are the least of our immediate 
concerns.) 


pastedGraphic,tiff 

Apple Event code entries always have four characters, 
and SuiteModeler enforces that constraint. Apple has 
reserved the space of codes comprising all combinations of 
four lower-case letters, so always use at least one upper-case 
letter in your codes, (Beware: if the trailing characters are 
spaces, that fact won't be apparent in “PropertyList Editor” 
unless you select the entry.) 

Commands 

We start with the two Commands. In the “Commands” 
tab, use the upper button to add thwo entries. Their 
names appear initially as MyCommand, and 
MyCommand^l. Enter the values for the fields in the upper 
table as shown (use any string for the descriptions). Rename 
them and enter the other fields as shown. Notice that 
SuiteModeler generates some fields for you: given a name, it 
guesses the external name, Given an external name, it 
guesses the plural and sometimes, it can correctly guess the 
appropriate Apple Event Code value. 

1__pastedGraphlc,tlff " 

The ReCeiiter command takes no arguments and yields 
no result. It simply re-centers the dot in the view and serves 
as an example of the simplest kind of command. With the 
Reverse command selected, use the button in the lower 
tai>le to add its string argument as shown, The Reverse 
takes a string as an argument and returns a string of the same 
characters in the opposite order (just to demonstrate an 
AppleScript command with an argument and a return value). 

Classes 

Our suite has two classes. In the “Classes” tab, use the 
upper but ton to add two entries. They appear with 

MyCiass and MyClass_l in the “name” column, again with 
default entries in the other columns. 

The DotDocument Class 

In the first entiy, type in DolDociiment in the “name” 
column, SuiteModeler generates its external name and plural, 
so these entries are in gray. Type in docu for its Apple Event 
Code, and NSCoreSuite,NSDocument as its superclass. 
Here, weTe using the code docu from the core suite, so it's 
all lower-case. The .superclass entry appears in red denoting 
an unresolved reference, (To resolve the reference, open the 
NSCoreSuite from the "Open Recent” menu. This entr>' then 
appears in black.) Type in an entry for the description. With 
tlie DotDocunient row still selected, choose the “Attributes” 
tab in the lower half of the split vlew\ Then use the lower 
button to add an attribute. Set its name to dot, its type to 
Dot, its code to xDoC and set the “[r/o]" or Read-Only 
column entry to Y or y. SuiteModeler will complete the entr>\ 
SuiteModeler constrains the entries for the sex and number 
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columns in a similar way —just type in the first letter of your 
choice. 

The Dot Class 

The entries for the Dot class follow from the screen shot. 
(Once you’ve typed in its name, the reference to it in the 
DotDocument class should appear in black.) Notice that its 
external name, dot. appears in blue (multtpie references), 
and its code, xDot, appears in grey (default) to indicate that 
all (here, both) items watli the same external name have the 
same code. 

2 _!@%l#_pastedGraphic.tiff 

3 _#$! i if_paste d G ra pM.c. t if f 

Tying Classt^s to Commands 

For each of the two classes, add supported commands as 
shown. Had we not defined these commands first in the 
“Commands'* tab, their names would have appeared in red“ 
perhaps a little alarming for an introduction. Again, given the 
name for a supported command, SuiteModeler calculates a 
method name. 

4 __pastedGraphlc .tiff 

5 _#$! t _pastedGraphic, tl ff ** 


Tm #1 Relational Database on Mac OS X 

OpenBase SQL 7.0 



Tool Tips 

The headers of the columns of all the table views in 
SuiteModeler provide tool tip suppon. Kach column's tool tip 
associates a key with the lext from the corresponding tables of 
the documentation in 

file:///Developer/Docuinnentation/Cocoa/ProgrammingTopics/ 

Scripting/SuiteDefs 

The exception is the “ext. name” column. It shows the 
synthetic “HumanReadableName” instead of “Name,” which is 
the key associated with the “name” column. 

Conflicts —a Demonstration 

As an experiment, temporarily make a conflict of codes and 
external names. Change the code for the dot class from xDot to 
yDot then switch to the “Summary” tab. You'll see that suddenly 
the codes and external names involved in the conflict appear in 
red. If you try to save the suite document in such a state, 
SuiteModeler will warn you. Change it back to xDot, 

6 __paBtedGraphic .tiff 

Some readers may choose to complete this exercise 
successfully, then build in a conflict and explore the 
consequences. 

Save 

If youVe not bought a license, use the result supplied. 
Otherwise, save the result as DotSuiie, using the default choice, 
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docament wrapper, for the output file format. The wrapper 
contains the definition and lenninolagy files. Check it against the 
version supplied. 

You could also reproduce the work in the Tropertylist 
Editor” application, but you’il have to read the documentation 
more carefully to produce a working suite that way. Choose a 
non-trivial existing suite, say NSCoreSuite to compare 
SuiteModeler and Tropertylist Editor” You’Ll find the 
SuiteModeler presentation more compact and unified (after all 
—^using “Propertylist Editor," you have to open two documents, 
the definition and the terminology). Certainly, when you 
compose your own suite, SuiteModeler's validation, automatic 
generation of default values, and cross-referencing features will 
save you some headaches. 

The ‘Naive’ Objective-C Files 

SuiteModeler also emits a directory of Objective-C files 
when it saves a suite document. Open all the Objective-C files 
in the document wrapper now. Each class in your suite results 
in a and a *.m file. A single Mi file declares any enumerations 
in the suite. For each class, it provides instance variables and 
accessors for each attribute/property and property/elenieni 
(only the ‘"getter” metliods for the read-only cases). It also 
declares and provides a base implementation for each .supported 
command, declaring and extracting any command arguments. It 
also declares and implements a class method that provides an 
array of keys useful for KVC. It also provides some support for 
object specifier methods. 

Implementation —Step by Step 

SuiteModeler will not emit cill the code necessary to 
implement your suite, and the class files will likely not compile 
as emitted. In each case, you’ll need to add or modify a few lines 
itj import the parent class, and to import or declare any other 
classes referenced (perhaps using “@class” in the *h files). You 
may need to import these frcmt your own frameworks. However, 
SuiteModeler has saved you lots of typing. As a developer, you 
iniJsl provide the underlying logic specific to your “Model” — 
that’s why “My Great Software, Inc." pays you the big liucks. For 
each class, Dot and DotDocument, we explain the few lines we 
modify' to compile the naive file. Then we add categories of 
“Model” logic to each. 

First well build and test a simple application. Then we will 
repackage it by moving two classes into a framework. We will 
also make the framework scriptable. Well re-compile and test 
the repackaged code. Then Wee’Ll drive the resulting compiled 
application with an AppleScript suite. 

Start with a Cocoa Document-based project. It provides a 
generic “MyDocument" class—keep it. Add the Dot and 
DotDocument files to the “Classes” group, “by copy” from the 
suite document wrapper. We’ll move them into a framewc^rk 
later. For the methods below, find their implementations in the 
completed project. 

In this exercise, we will rely on several categories in 
separate files. A category encapsulates a group of related 


methods, llie author hopes that by isolating these categories in 
separate files, the reader will find it easier to track differences 
using FileMerge. (The XML methods for NSDictionary can prove 
generally useful.) Otlierwise, this exercise takes the notion of 
categories and protocols perhaps a bit too fan 

Initial Details —^Imports and Declarations 

[1] In Dot.h, add 

gclass DotDocutnent I 
just before the “^interface ...” line, 

[2] In DotDocument.h, comment out the line 
/flniport ‘'NSDocument .h" 

We get reference to that class w^hen we import the <Cocoa> 
framew^ork. 

[ 3 ] Al.sc in DotDocument.h, add 
Sclass Dot: 

just before the “©interface ..." line. 

[4] In DotDocument,m, import the Dot class. Add 

#iinport **Dot.h'* 
just after the existing import, 

[ 5 ] in Dot.m, import DotDocument.h similarly. 

Tile changes so far sliould permit you to compile the ’naive' 
files, but tlie compiler will w^arn about unused variables. 

Add a Category of XML Methods to NSDictionary 

Add to your projects by copy the files 
NSDictionary+XMLMethods.h and *m (provided in the 
ScriptableDotView project). You may find this category generally 
useful. See Brian Web.ster’s post on tfie OmniGroup Cocoa Dev list, 
http ://www.omnigroup, com/rrailfTi a n/archive/macosx-dev/2001- 
January/008625.html 

One might reasonably expect Cocoa API for this. As things 
stand, we drop down into Carbon. 

Repackage the MyDocument Methods as a Category 

Project Builder provides some ObjecUve-C code in die 
generic “MyDocument" class. Convert the MyDocument class to 
he the DotDiKument+Subdassing category. Rename the ‘.h and 
*m files, change the import statement in the ‘.m file, and change 
the ©interface and ©implementation lines to support the 
category. They become 

^interface DotDocument (Subolasalug) 

and 

^Impletnentatlon DotDocinnent (Subclassing) 
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(and delete the pair of curly braces in the ‘.h file). Also in 
the *.m file, change the windowNibName meihod to return 
@”DotDocument". 

Augment DotDocumcnt+SubcIassing For XML Persistence 

In the *.rn file, import NSDictionary+XMIMethods.h and 
Dot.h. In the methods 

d a t aRep r e a ent ationO fTyp e * 

and 

loadDataRep raaantation:ofType: 

add the few lines necessary to provide XML persistence. 
Notice chat KVC makes this really compact* Compare with 
SKTDrawDocument in the Sketch example. Sketch re,sorts to 
the methods -ISKTGraphic propertyListRepresentation] and 
+lSKTGraphic graphicWithPropertylistRepresentatianl and 
their overriding implementations in the subclasses of 
SKTGraphic. If we had comparable subclasses here, we 
would only need to override the +kvcKeys method in each 
subclass (assuming we had already written the matching get 
and set mctht>ds anyway). Remember that any code you 
don't have to write is code you don't have to debug, either. 

Add DotDocument+ModelControUiog as a Category 

This category comprises two methods. One writes 
‘'Model'' information to the '‘View,” and the other writes 
"View" information to “Model.” Such a pair of methods often 
proves useful. Impori the DoiDocument+ModelConLrolling.h 
category. 

Add the NSView+DotViewing Protocol 

This protocol declares one method. It will become part 
of the framework. The application will have a DotView cla.s.s 
that conforms to it. 

Add Model-Controller Instance Variables and Logic to 
DotDocument 

In DotDocument*h add these instance variables 

iBOutlet NSView 

IBOutlet NSSlider “.slider; 

IBOutlet NSColorWell ".colorWell; 

and declare these methods: 

* (XBAction)vlewActioji: (id) sender: 

- (void) iiiodelCiia.nged: 

The view Action method responds to user interactions— 
mouse clicks and drags, and setting the color—and passes 
the information to the document, which sends it to the 
model. The modelChanged method signals the “View" that it 
must re~draw to reflect changes in the “Model." In 
Uocument.m, import the DotDocumeni+ModelControlling.h 
category\ It comprises two methods. One writes “Model” 
information to the “View,” and the other writes “View” 


information to the "Model.” In this class, they're both 
empty—we’ll override them in DotDocumem to do useful 
work. Add the awakeFromNib meihod to initialize the 
“View.” Find the implementations for these methods in the 
completed project. Add an init method that initializes the 
document’s instance of the Dot class. Add the awakeFromNib 
method to initialize the “View." 

Augment the Class Implementations with Custom 
“Model Logic’^ 

Declare and implement the iniiWithDocument: method, 
and import “ DotDocument. h". DotDociiment’s 
handleReCenterScriptCommand; and Dot’s 

liandleReverseScriptCommaad: both require fewdiner 

modifications. We can’t save NSCoior in prciperty list form 
directly. As in the Sketch example, well have to archive 
NSCoior as NSData. WeTe not free to replace the naive color 
accessors —AppleScript needs them—so we’ll supply two 
more to access the color attribute as archived NSData. Be sure 
to change colorKey to colorDataKey so our kvcKeys method 
can support XML persistence* We’ll come to the remaining new 
instance variable and the initializer later* 

Steal Your Interface 

Open the MaimMenu.nib document of the DotView 
example and copy its Window component (it has the view, 
color well, and .slider). Open your project's My Document, nib 
file, delete its Window component and replace it with the 
one from DotView. Drag the DotDocumeni.h file from 
Project Builder’s files pane onto the My Document panel, so 
Interface Builder can parse the file. Set the File's Owmer to 
he DotDocument, Delete My Document from your nib. 
Disconnect the actions for the slider and color well, and 
connect them to the File’s Owmer, choosing the viewAction: 
method* Save the result as DolDocument.nili. 

Adjustments for Fit and Fttiish 

Choose your project’s “Targets" tab. In the “Application 
Settings" tab and using the “Expert" settings, set the 
document cla.ss to be DotDocument and set the file 
extension to he dot. Choose the “simple" settings and set the 
document’s extension to dot. 

First Test 

The application should compile and launch after you 
have made these changes. It should be able to save and open 
its documents in XML form* 

Make it Scriptable 

Under the application target’s application settings tab, choose 
the “expert" settings and add a new sibling called 
NSAppleScriptEnabled. Set its value to the string ^'ES, Add to 
the Resources group die files DotSuite.scriptSuite and 
DoiSuite.scTipiTerminology from die DotSuite.suiteDocument file 
’wrapper provided, using the “by copy” option. Localize the 
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lemiinology file (select it in the Files pane and “Shtiw Info"'). Be 
sure that these files are checked as part of the application taiget. 
Recompile. Now, Script Editor should he able to browse to your 
project's ""build” directory and open your application's dictionary. 
Also, the script provided should properly drive your application. 

One More Step —Repackage the ‘‘Moder classes as a 
Framework 

Refer to the article http:/Mww.cocoadevcentral.coiTi/tutortals/ 
“Frameworks Within the App Bundle’' by Brian 
Christiansen, Cocoa Dev Central 

Following the article, set the framewY^rk's installation 
location to the path: 

@executable„path/,,/Frameworks 

and add the linker flag 

-segladdr 0x10000000 

as detailed there. 

From the “Project menu, choose “new target.’' Choose 
its type to be Cocoa framework. Set the name of the 
framework target to be Dot. In the Target pane, set the Dot 
target to be ‘under’ SeriptableDotVlew (that is, to make 
ScriptableDotView, you must first have made Dot. ) 

In the File pane, add a new Group called <Dot> and select 


it. Move the NSView+DotViewing protocol and tlie Dot and 
DotDocyment classes into the new group. Remove them from the 
application target and add them to the framework target. Be sure 
to set those headers to “Public.” Similarly, move the 
DoLSuite.scriptSuite and DcitSuite scriptlermincdogy files to the 
framework. You'll also need to drag the Dot,framework element 
in the “Products" gremp in the Files pane to the application target's 
“Files 8l Build Phases" tab's “Frameworks Be Libraries” fields. 

QED 

Compile and run the application. If it fails, compare your 
project against the supplied ScriptableDotView project. You 
should be able to verify that the requirements have been met. 

Conclusion 

We’ve used the SuiteModeler application to compose a 
Cocoa AppleScript suite as an expression of requirements. We've 
developed a framework and application on it that support our 
AppleScript suite, starting from the Objective-C files 
SuiteModeler emitted, adjusting only the imports and declares, 
and adding just a few lines of “Model" logic. We have used Key- 
Value Coding both in the suppon of our suite and to simplify 
XML persistence of our document-based application. We have 
used AppleScript to test our implementation. Readers can now 
build their own script-enabled Cocoa applications and 
frameworks more easily. 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boomtra, Westford, MA 


Jigsaw Puzzlje 

1 do jigsaw puzzles in stieaks. I’ll go for years without doing 
one. After all, there is sc^iiiething ftmdamentally wasteful about 
spending countless hours on putting something together tliat is 
destined to be disassembled and put back into the box. Then again, 
rll find myself on vacation welcomed l^y several days of soaking 
rain, and Til stait one. If you're like me, it’s impossible to stan a 
puzzle without finishing it. Doing so wotild be admitting defeat, and 
one cannot allcjvv tjneself to be defeated by something that lives in 
a box in the closet. I also refuse, unlike some members of my 
immediate family, to cheat by using tlie picture on the box cover to 
help solve the puzzle. At least 1 don’t do tliat while anyone Ls 
looking. Occasionally, some sadist will give me a puzzle as a gift, 
usually one that has some impossible picture, or one that has 
impossible shapes, or one tliat is a single color, etc. This monlli, 
thanks to the suggestion of Peter Lewis, it's my turn tcj torture you 
with a jigsaw puzzle Challenge. And I’m not giving you a box cover 
to work with, just in case yoifre inclined to cheat. 

Your puzzle has no color infonnation to help you in a.sseinbling 
it ” you’ll have to rely enlirely on the shapes of the pieces to 
detennine where each piece Ix^Iongs. When assembled, the puzzle 
has a rectangular shape, 'fhc puzzle is presented to you as a [bitmap 
of l6-l:jit pixels. Each piece consists of contiguous pixels with a 
unique nonzero pbie] value. 'lEe pieces are rotated by a multiple of 
one-quarter turn, and are scattered lluoughout a recliingle, with no 
overlap Ixftween pieces. Pixels not containing part of a puzzle piece 
have the value 0, To eliminate any ambiguity in the cineniation of 
the reassembled puzjtle, the t{ )p left corner piece will be lcx:ated in 
iLs final position at location (0,0) of die puzzle rectangle. Your job is 
to reassemble a series of tliese puzzles as efticiently as you can, 

The file challenge.in contains a .single line with the numlier of 
test cases yc]ui pn:)gram needs to process. The input for each test 
case is provided in file jigsaMvNN.iii, where NN ranges from 1 to the 
number of test cases. Each input file contains 
(2+puzzleHeight*puzzleUlddi) 16-bit values, corresprending to this 
Jigsaw^Puzzle structure: 

typedef struct JigeawPuzzle \ 

short puK^leJieight: f* numlicr of mws in tlic piUi/Jc or hiimap */ 
short puzaleWldth: /* niinil:K:r of columns in tlie puzzle or bitmap V 
short *pu2zleValue: 

r pii»JcValiH;|n>w’puia:lcWidth+t:()Il is ihc (n)w,ail) puj/Jt V 
/* pu^L'Valuc = 0 is an cin|3ty pixel V 
/* puzzleValuc = n is pan of pkee n 7 
I JigaawPuEzle; 

Your code needs to read each input file, reassemble the puzzle 
by rotating and translating individual pieces, and output a 
Jigsaw^Fuzzle structure containing die solved puzzle to die file 
jigsawNMout, With no space between the reassernliled puzzle pieces, 
file reassembled puzzle will have a smaller width and height tlian 
the input bitmap. 

Your program shotdd produce a challengalog file, with one line 


I>er test case containing the integer number of micraseconds used by 
your application to solve that test ca.se, including the time to read die 
input, find the solution, and produce the output file. The method 
used to measure execution time may vary based on the development 
environment you use for your solution, liut you should measure dme 
with microsecond precision if poSvSible. 

You can improve your chances of winning by incorporating 
opdonal features into your solution. For this jigsaw puzzle problem, 
you might want to optionally display your solution's progress in 
solving die puzzle. The timing of your solution should exclude any 
opdonal display features. 

Scoring wiJl lie based on minimizing execution time, on a 
subjective evaluation of additional features, and tm die clarity of your 
ccKle, including the commentary that describes your solution, use of 
coasistent naming conventions, and die readability of your code. 
Your base score will lie 1 penalty point for each microsecond of 
execution time. Penally points will he decreased by up to 25% based 
on any optional features you might incorporate into your soludon, 
and by another 25% based on a subjective evaluation of die clarity 
of your code. 

This will be a native l7)werPC Challenge, using the 
development environment of your choice, provided I have or can 
obtain a copy - email piogchal!enge@mactech.a>m to check before 
you start. You can develofi for Mac OS 9 or Mac OS X. Your solution 
should be a comfilete Macintosh application, and your submission 
sliould provide everything needed to build your application, as well 
as documentation of the features you have implemented, to ensure 
dial 1 don’t overlook anydiing. 

Winner of the February, 2002 Challenge 

Congraiuladons to Allen Stenger for winning the February 
S’xChart Challenge. This Challenge involved convening a set of input 
nodes and connection inforniation, inspired by a mildly salacious 
web story^ involving "connections” among members of the internet 
community, in a way that minimized inteisecdons lietween lines in 
die resulting gmph, and also minimized execution Lime. Allen’s 
.s{)IuUQn produc ed .significantly fewer intersectioiis than the second- 
place (and only otlier sulimitted) .solution by Ernst Munter. 

Allen and Emsi used very different techniques to generate dietr 
graphs. Alien always connected vertices using a single line segment; 
Ernst used multiple line segments io connect vertices. Allen used a 
’‘spring emliedder" algorithm to iterate tow^ard a planar graph, wadi 
a repulsive force between nonconnected vertices and a .spring-like 
force betw^een conneaed vertices that tends to keep vertices .some 
nominal distance apart. The algorithm is described in the 
commentary to file CGraphEmbedder.cp, and in a referenced article 
in Dr. Dobbs Journal. Ernst focused more directly on minimizing the 
number of intersections between line segments. As it mmed out, 
Allen’s solution required much more execution time, but generated 
fewer line intersections. 
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Allen also provided more optional features in his submission, 
taking advantage of PowerPiant to produce Ms application. Both 
ccjntestants provided scrolling and window resizing capaliilities that 
allowed the entire graph to be displayed. Allen also provided a 
zoom cap^ibility and menu options tliai provided independent 
control of the creation and the display of individual graphs in the 
lest data sets. Ernst's display was somewhat more attraaive, placing 
all nodes completely witliin tlie visible area of tlie graph and framing 
the names associated with each node. Alien won a slightly higher 
bonus score lor opiionai features, as well as a larger penalty for 
execution time, but hLs win was due to die signillamtly smaller 
numMr of graplt intersections produced by his solution. 

The table below lisLs, for each of the solutions submitted, the 
number of intersections in the graphs generated, the total execution 
time in millLseconds, the txrnus awarded for optional program 
features, and ilie cumulative score. It also lists tlie code size 
(excluding the PowerPiant code in Stenger\s solution), data size, and 
programming language of each entry. As usual, lire nuinlx.T in 
parentheses after the entrant s name is the total numlier of Challenge 
points earned in all Challenges prior to this one. 


Name 

Score 

IntcTscctioas Time 

Ikifius 

taHk 

f}ata 





(tnscs:) 


Sire 

.Sire 


Atiin Stenger 

9111.33 

9903 

l!i53'iS.t)0 

2im 

113944 


C++ 

Erasi MiiiiEtt (852S 




18.7% 

22«('. 

m 

C++ 


Top Contestants 

Listed here are the Top Contestants Ibr the Programmer's 
Cliallenge, including everyone who has accumulated 20 or more 
points during the past two years. The numliers below include 
points awarded over the 24 most recent contests, including 
points earned by tliis niontlPs entrants. 


Rank 

Name 

PoinLs 

Wins 

Total 



(24 mo) 

(24 mo] 

Points 

1 . 

Munter Em.M 

m 

m 

H4Z 

2. 

Saxton, Tom 

52 

1 

210 

3- 

Wihlbf>;g, Claes 

47 

2 

49 

i 

llicken. Willi-kt 

46 

2 

134 


Stenger, Allen 

39 

1 

m 

k 

Taylor, Jonathan 

39 

1 

63 

9. 

Gregg, Kan 

m 

1 

14(1 

JQ, 

Mallett,Jeff 

m 

1 

114 

11 . 

Cooper, Tony 

20 

1 

20 

12. 

Tiusfckr, Peter 

20 

t 

20 


AND THE Top Contestants Looking for a Recent Win 
In order to give some recognition to other panicipants in the 
Challenge, we also list die Mgh scores for contestants who have 
accumulated points witliout taking first place in a Challenge during 
the past two years. Listed here are all of those contestants who 
have aceumulaied 6 or more points during die past two years. 


Rank 

Name 

Points 

Total 



(24 mo) 

Points 

7. 

Sadeisky, Gregory 

22 

24 

8. 

Boring, Randy 

21 

144 

13. 

Shearer, Rob 

19 

62 

14. 

Schotsman, Jan 

16 

16 

15, 

Hart, Alan 

14 

39 

16. 

Nqjsund, Ronald 

10 

57 

17. 

Day. Mark 

10 

30 

18. 

Desch. Noah 

10 

10 

19- 

Fazekas, Miklos 

10 

10 

20. 

Flowers, Sue 

10 

10 

21. 

Maurer, Sebastian 

7 

loe 

22. 

Leshner. Will 

7 

7 

23- 

Milkr. Mike 

7 

7 


Iliere are three ways to earn points; {!) scoring in the top 
1 of any Challenge, ( 2) being the first person to find a bug in a 
puhlislied winning solution or, (3) being the first person to 
suggest a Challenge that I use. The points you can win are: 


Lsi place 

20 points 

2nd place 

10 points 

3rd place 

7 points 

\{h place 

4 jxiints 

Sih place 

2 points 

finding bug 

2 points 

suggesting Challenge 

2 points 


1 lere is Allen's winning S^xCharl solution: 

SxChartApp.cpp 
Copyright © 2002 
Allen Stenger 

iuifiiimiiuiiufniimuiiiuimmiifuiiiiiifuimiiimmu 

a 

// S‘xChan (MacTc-ch Prugranimer s Chiilk-nge, Fcbnwry 2t)()2) 
//Wriltcn by Alk-n Sicnj^Tjiinuary 2002 

// 

// This file Includes pc^rtions of: 

// t :Bask-App.cp, ® 199^4-21 X) I M ctn werks I nc. Al I aserwd. 

// Pni)i:i:i is |>iscd tm tbe McLrtJWtrks Iksic Applicatitjn staiionerv, 

// 

//We Jissume the files are in ihc same folder as the application, 

//Wc a,^sunic tJic Itics arc nymt>cred starting at 00. 

// 

// Our strateg): 

// 

//Ttic diaUcngt b to pn>ducc a planar embedding (or almosi planiu:) 
// of a given graph. We detemime the connected components of the 
// given graph and apply a'^spring embedder" algorithm to each 
// eomixment (the spring eml^edderdoesnl work on disconnected 
// graphs),Then we shift each component so they arc stacked 
// vertically, not intersecting each other More detaib of the 
// spring embedder are given with its code. 

// 

//To display the graph, we create a Picrure in memtiry and draw 
// the Picture into the display window. 

// 

////////////////////////////////////////////////////////////////////// 

tfinclude "SxChartApp.h" 
ffinelode "CGraphEmbedder. h*" 
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^include "CGrapbWindow-h" 

/include <LGrowZoi!ie .li> 

#include <PP_Messages.h> 

^include <PP_Reisources,h> 
ifinclude <tJBrawingState. h> 
i/lnclude <UMeiiioryHgr .h> 

^Include <URegistrar*h> 
i/iTiclude <LActiveScroller. h> 

Hnclude <LWindciw.h> 
ifinclude (LCaptlon.h) 

/Hncliide <ctiine> 

^Knclude <fstr€ajn> 

^Hnclude <satream) 

/include <Etring> 

/^Include <vecti?r> 

// == =^ =====:= :^-^-^=:= = ===== = = = = = == == ==== = = = = 

// ■ main 

- 

int niainO 
I 

// Sei Debugging options 
S etDebugThrow_(d ebugAction_Alert ): 
SetDebugSignal_(debugAction_Alert); 

// InitiaiiZfC Memor}^ Manager. Itameter is the number of 
// master pointer bhKks ui allocate 
InltlallzeHeap(3); 

// Initialize standard Toolbox managers 

UQDGlobals:;InitialiaeToolboxC); 

// Install a GrowZooe to catch kiw-memory siiiLHions 
new LGrowZone{20000); 

// Create the application object and nm 
SxChartApp theApp; 
theApp.Run{): 

return 0; 

I 


// * SxChartApp fpublic| 

// Application object constructor 

SxChartApp::SxChartApp[) 

( 

RegisterClaases(); 

j 


// ‘ “SxChartApp [public, virtual] 

//- 

// Application object destructor 

SxChartApp::“SxChartApp() 

I 

// Nothing 

1 


if -— 

// • Obej.'Qjinmand [public, virtual] 

/y Respond to Commands. Returns true if the Command was handled, false if not. 
Boolean 

SxChartApp;: ObeyCojimiand ( 

ContmandT inCoumjand. 
void* ioParam) 


Boolean cmdHandled ^ true; //Assume we’ll handle thecominand 

switch CinCommand) [ 

case ciiid_RunAllTests: 

I 

UGursor:; SetWatcb (); // a slow operation ■ show watch 
RnnAllTestsO ; 

1 

break; 

case ciiLd_RuiiOiieTest: 

j 

int runOneNuraber; 

if (AskForTestNuraberC&runOneNumber)) 

I 

UCursor: : SetWatch (): // a slow operation - show watch 
RunAndLog (runOneUnraber, rUnOnaNuinbet) ; 

] 

1 

break: 

case ciitd_DrawGraph; 

1 

Int drawOneNuinber; 

if (AskForTestNumher (^idrawOneMumber)) 

I 

DrawGraphCdrawOneNumber] ; 

I 

I 

break; 
default: f 

cmdHandled = LAp pllcat ionObey Command (inCamand » 
ioPacara): 

break: 

I 


return cmdHandled; 

1 


// • FindComnundStuius [public, virtuall 

If Ikiermine tlie smtu,s of a Command for the purposes of menu updating, 
void 

SxChartApp::FindCommandStatUs{ 

ComtaaudT liiGommaiid, 

Boolean^ outEnabled. 

BooleanSi outUsesMark* 

UlntlbS outMarkt 
Str255 outName] 

[ 

switch (inCommand) I 

case cmd_RunAllT€ata: 

\ outEnabled “ true: I 
break; 

case crad_RunOneTest; 

[ outEnabled = true; I 
break; 

case cind_DrawGraph: 

1 outEnahled = true; 1 
break; 

default: ] 

LApplication::FindCommandStatus[inCommand, outEnabled. 

outUsesMark* outMark* outName); 

break: 

1 

] 


// • RegisterClasses [protected! 
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// To reduce clutter within the Applicaiion object's constructor, class 
// registrations appear here in this separate funaion for ease of use. 

void 

SxChartApp::RegisterClasses() 

( 

ReglsterClass_(LWlndow ); 
ReglsterClass„(LCaptlon): 
ReglsterClaBs_(LDielo.gBoK) t 
RegisterClass_(LEditField); 
RegisterClas£„(LStdButtoii): 
ReglsterClaBs_(LActiveSGroller): 
ReglsterClass_(CGraphWindow): 
ReglsterClass_(GGrapliVlew); 


iiiiimuiimmmmuimiiiimimmimmmimm 

// SxChartApp-spccific functions 

Std;:string ExChartApp:iTestNumberToStringCint testNumber) 

std: lostringstream flleNuajberStreaia; 
fileNuniberStream*width{2): 
fileNumberStreaTii.fillCO’) ; 
fileNunberStreatn << teatMutnber; 
return fileWumberStreain.strO \ 


void SxChartApp: iSayFlleError(const std::string &rFileNaT]ie) 

I 

std::string eerorString = “Sorry, could not open the file 
“ + 

rFileNaiiLe + 

Str255 errorPString: 

::CopyCStringTQPascal(errorString.c_srr{}. errorPString); 

: t ParamText (errorPStrlng, "Vp**, > “Vp"); 

UModalAlerts::StopAlertfkfllankALRT); 


void SxCbartApp::RunAllTests() 

I 

// fetch number of tests, run each test, and output log entr>' 
std::ifstream uumTestsStreamf“SexChart*in“): 
if {lnuraTestsStrearn,ls_open()) 

SxChartApp::SayPileError (“SexChart *iii**) : 
return: // give up 

I 

int numTests = 0 : 
numTestsStream » nuaiTests: 
numTestsStrearn^closeO : 

RunAndLogCO, tiutnTeEtE - 1 ): 

I 

void SxChartApp::RunAndLog(int startCese, int endCaseJ 

std:: of stream logStrean {/'logfile * ixt"): 
if (llogStream.is_open{)) 

I 

SxChartApp:;SayFiXeError(“logflle,txt"); 
return; //give up 

) 

for (int i = atartCase: 1 endCase: i++) 

std:;clock_t startTime, eudTime, elapaedTijneClocks; 

startTime = std::clock(): 

RunOneTest(i): 
otidTime ^ std : :clock() ; 

elapsedTimeClocks = endTime - startTime: 
long elapsedTimeMS = 

std::floor((lOOO * elapsedTimeClocks) / 
CLOCKS_PEE_SEC + 0.5): 
iogStream « elapsedTimeMS « std:;endl: 

J 

logStream.closed : 

1 

void SxChartApp::RunOneTest(int testNumber) 


bool bOkSoFar = true; 

CTestiunner aRunner(testNumber): 
bOkSoFar ^ aRunner.LoadNames(): 
if (bOkSoFar) 

bOkSoFar = aRunner.LoadHookups(); 
if (bOkSoFar) 

{ 

aRunner .MakeEmbeddedGraphO: 
aRunnsr.WriteLocatlonsC 5 : 
aRunner.WrlteSegments(): 


bool SxChartApp: :AskForTeEtNiimber(int 'pTestNimber) 

SInt 32 ioNumber = 0 : 

bool bOk = DModaiDialogs::AskForOneKumber( 
this* 

kAskTestWumberDLOG, 
kAskTestNumberEditPane. 
loNuinber) : 

if (bOk) 

'pTestNumber = ioNujtber; 

return bOk; 

I 

void SxChartApp::DrawGrapb(int testNuraber) 

£ 

LWindow ‘pGraphWlndow - LWindow::CrGateWindow[kGrapbWindow, 
this)I 

std::string titleString = “Graph*' + 

TestNumberToStringi testNumber): 

•Str 255 tltlePStrlng: 

::CopyCStringToPascal(titleString,c_str(). titlePString): 
pGrapbWindow->SstDGSOriptor(tltlePString): 

CGtaphView *pGraphView = 
static_cast<GGraphVlew *> 

tpGraphWindowOFindpaneByH} (kGraphView)): 
pGraphVlew->LoadGraph(testNumber); 


////////////////////////^^^^^ 

// CTesiRunner imp]cnieni:itk>n 

GTestRunner::CTestRunner[int testNumber) : 
fNinit^Tertlces (D) , 
fNumHookups (0) , 
fp Graph (0) 

I 

fFileHumberString “ 

SxChartApp: :TestNumberToString(testMuinher) ; 

1 

CTestRunner::^CTestRunner() 

I 

delete fpGraph; 
fpGraph = 0: 
f 

bool CTestRunner: rLoadJ^amesO 

I 

// 0(>cn correct name file 

std: :oEttingstreaiii flleHameStream: 

fileNsmeStream “names'’ << fFileHumberString iK “.in": 
std::string fileHame[fileNameStream.Etr ()) ; 
sLd: jifstrean] nameStream [flleNanve. c_str ()): 
if (1 namestream,is_opGnC}) 

I 

SxChartApp; :SayFileErcor[fileName): 
return false; //give up 

1 

// read number of names 

std::string numNamesStting; 

std::getline(naroeStream, numNameEString); 

int ntLfflV'ertlcGS = std ::atoi (numWamesString. c_Etr [)): 

// read all name lines 

for (fNumVertlces = 0; 
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fNmVertices < numVertices InameStream.eof CJ; 
fNuin¥GrticeB++} 

I 

std;: string naineLine: 

Std*: gGtline (nameStreain* naaeLlne): 
fNames^push^hackCnameLine): 
t 

name St ream, close () : 

// create gaph tills siijc 

fpGraph = new CMyGraphCfNiunVertices): 

// sort names 

std::sort(fNanies.begin{) . fNames.endt)): 
return true; 

1 

bool GTestRurmer:rLoadHookupa() 

( 

// open correct hookups file 

std: :oBtringstreain flleNameStreant: 

fiieNameStreara « “hookups" « fFlleNumberStritig « “.In": 
std: :string flleNanieCfileNameStreani.str {)): 
std: tifstreant hooknpEStrea!iiCflleName.c_str{)) ; 
if (IhookupsStream.is_open()) 

( 

SxChartApp::SayFileErrnr(fileName): 
return false: //give up 


// mad number of hookups 

std::String numHookupsString: 

std:igetlineChookupsStream, numHookupsString): 

int nuniEooknps = std: :atoi(numiiookupsString.c_str ()): 

// read all hookup lintii 
for (fNumHookups = 0: 

fNumRookups C nuinfiookups &£■ IhookupeStream.eof (3: 
fNumE□okups++) 

( 

st.d::string hookupLine: 

std :: getline {hookups St ream ♦ hookupLine); 

LoadOneHookup(hookupLine): 

1 

hookupsStream,close 0: 
return true; 


void CTeatRunner::LoadOneHookup(const Etd::stringi 
rHookupLine) 


t 

// format of line is 
// penionA,personB 

fitd::string::si3G_type firstCoimna ^ rHookupLlne.find(\ : 

std;:string personAName ^ rHookupLlne.substr[0* 
firstCoama): 

Etd:: string personENanie = rHookupLine.snbstr(firstCamma + 

1 ): 

std::vectqt<std::string)::iterator iter = 

Etd: :lowsr_bottnti(fNames.beginf). fNaraes.endO . 
personAName): 

int personAIndex = iter - fHames,begin(): 

iter = std::lowGr_bound£fNames.beginC)* fNames.end£}. 

personBName): 

int personBIndex = iter - fNames.begin(): 

fpGraph->SetAdjacent(personAIndex. personBIndex): 

I 

void CTe s tRunn e r::Kake Embe d d ed G ra p h £) 

1 

// Qnd out the connected components 
fpGrapb->FindConnectedComponents(): 

// Lay out all the points. 

// We place tlie points at the vertices of a regular ii-gon 
// of ibeed diameter; this is somewhat arbitrary; if we had 
// Mime idea of the final graph we could places tlte points 
// closer to iheir final position, 
const int kDiara = 1000: 

// diameicT of cimle circum.scrjhing n-gon. units: pixels 
const float kPi = 3.14159: 
for £int i = 0: 1 < fNuinVertices: i+t) 

[ 

Point vertex: 

double angle = i ‘ 2 ‘ kPi / fNuntVertices: 
vertex.h ^ static_cast<int>(0.5 + 

kDiam * D.S ’ (1 + std:: cos (angle))) : 
vertex.V = static_cast^lnt>f0.5 + 

kDiam ^ 0.5 * (1 + stdr:sin(-angle))): 
fpGraph->3etVertex(i. vertex); 

J 

// embed each compotieni in a plane^ then shift it so it doesn't 

// coOide with the other components. We align each component flush 

// left and just below the previous component. 

int newCompTop = 0 : // where to put nest component vertically 

int nntQContps = fpGraph->GetNuii!Coiiiponents (}: 

for (int whiebComp - 0: whichComp < numComps: whiehCoiHp++) 


VOyVE GUI YOGR NEW MAC. GREAT. NOW AEE YOG WANT TO 00 
IS PUBEISN A SIMPEE. YET EEEGANE WEBSITE. CAEAEOG AM POSE YOON 
PIGEURES. DO SOME PUBEISOING. DO A EIIEEE DRAWING. MADE A EEW 
POE FITES. ARCHIVE SOME DOCRMENES ED SEND TO YDRR MDERER. CHE 
IE BDEEDNS FOR EHAE EEEGANE WEBSITE. MIMAIE EHEIA. 

Citii*" Pactlij SMreAnf RuRdl rnuCqueJi PstP^ SbjntfWn; 

^ A&r EtoE" TeWeb^ lfc»sv^ SImie'' 

I SlIESEinO' ffl (-» 

IT [HD icee TUAM ('onn dmldad now dr nsi ed www. wi 

M rlln I r\n NillN stone siwtoJ^SAmmj set yourHEiroDRAw^mAK 
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f 

CGraphEmbedder aEmbedderl'fpGraph, whichCamp); 
aEmbedder*EmbedComponent 0: 

*pCompBounds) 

1 

Rect bounds = [0, 0, 0. 0): 
bool bBoundsEmpty = true: 

Rect comp Bounds: 

FlndConiponentBounds(vhichComp. ScompBounds): 

for (int -whicliVertex ” 0: whichVertex < fNumVertlces: 

whichVertex++] 

MoveComponentCwhichComp. -compBounds.left. 

newCompTop - compBounds.top): 

( 

if (fpGraph->GetComponentNu]itber (whichVertex) = 
whichComp) 

// figure out where to put next component; 

// alltw a little margin between components 
const int kMargin = 20; //Units: pixels 

nevCompTop t- (compBounds,bottom - compBounds.top) + 
kMargin: 

} 

} 

I 

Point sVertex - fpGraph->GetVertex(whichVertex) ; 
if (bBoundsEmpty) 

1 

bBonndsEmpty “ false; 
bounds.top = aVertex.v; 
bounds.left ^ aVertex.h; 

void CTostRunner::WriteLocationE{) 

bounds.bottom “ bounds.top + 1; 
bounds.right - bounds.left f 1: 

t 

1 

// open conect output fde 

std:lostringstream fileNamoStream: 

flleNarneStream « “locations” << fFileNumberString << 

std: istring fileName(fileNameStream.str()): 
std::ofstream locationsStream(filoM3me.c_str{)): 
if (]locationsStream.is open(}) 

{ 

1 

else if {h:PtInRect(aVertex. Abounds)) 

[ 

if (aVertex.v < bounds.top) 
bounds,top = aVertex.v; 
else if (aVertex,v )“ bounds,bottom) 
bounds.bottom ^ aVertex.v f 1: 

if (aVertex.h < bounds,left) 

SxChartApp::SayFileEcror(fileName): 
return: //give up 

1 

bounds.left = aVertex.h: 
else if (aVertex.h ^ bounds.right) 
bounds.right ” aVectex.h f 1: 

for (int 1 = 0; 1 C fMnmVertices; i++) 

T 

j 

] 

1 

1 

Point vertex = fpGraph->GetVerte>cCi) : 
lonatlonsStreain << vertex.h ' h ’ ; 

locationsStream << vertex,v « ; 

locationsStream « fNameati] << std::endl: 

1 

*pCompBounds = bounds; 

1 

1 

locatlonsStreajn.closeO : 

1 

void CTestRunner:'MoveComponentClnt whichComp, int offsetH* 

int offsetV) 

1 

j 

void CTestRunner: : WriteSegments () 

1 

1 

for (int whlQhVertex = G: whichVertex < fMiamVertlces: 
whichVertex++) 

1 

1 

// open correct outpm file 

std::ostrlngstream fileMameStream; 

fileNameStreara << ^segments” « fFileKumberString << 

“,out": 

std::string flleName(flleNameStream.str()): 
std:: ofstream segiiientsStreain(flleWaiiie, c_Etr ()}; 
if (1 segmentsStream.is open(}) 

{ 

i 

if (fpGraph-^GetComponentNumber(whichVertex) = 
whichComp) 

1 

Point aVettex = f pGraph ■ )GetVertex(wMehVertex) : 
aVertex.h offsetH: 

aVertex.v offsetV: 

fpGraph->SEtVertex(vhicbVertex, aVertex); 

1 

SxChartApp:iSayFileErrorCflleName): 
return: //give up 

1 

1 

) 

1 

// we only need to generate lines in one direction, so we'U 
// always go from lower to higher indexes 
for Cint startVertex = Q: 

startVertex < fNumVertices: 
start?ertex+i) 

i 

CGraphEmbedder.c 

pp 

1 

for (int endVertex = startVertex + 1: 
endVertex < fNuniVertices: 
endVertexrH') 

! 

// 

// Graph Embedder 

//Written by Allen Sicngcnjanujiry 2002 

if (fpGraph->AreAdjacent(startVertex. endVertex)) 

[ 

// 

////////////////////////////////////////////////////////////////////// 

// we generate only straight-line segments, so 
// the number of points is :ilways 2 
segmeiitsStream iK ”2" stdi iendl; 

Point pointl ^ fpGraph-)GetVertex(startVertex): 
segmentsStreara << pointl.h << << 

pointl.v << std::endl: 

Point point2 = fpGraph*)GetVertex(endVertex); 
segmentsStream << point2.h « <C 

point2.v << std::endl: 

1 

1 

) 

//include “CGraphEmbedder.h” 

^/include string) 

a CGraphEmbcdder implementation 
// 

// Wc use a "spring embedder' algorithm/llicre are many varieties of 
// these; for a complicated example see: 

// “Simulating Graphs as Physical Systems" 

// Ame Frick, Georg Sander and Kathleeri Wang 
// Dr. Dobb's Journal. August 1999 

segmentsStream.closeO : 

1 

//The spring embedder pretends that: 

// 1. the vertices are freely moveable in the plane 

// 2. each edge Ls represented as a spring that has some nominal size; 

void CTestRunner:iFindComponentBounds(int whichComp, Rent 

// stretching or compressuig the spring creates a restoring force 
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// that tries to return the spring to its nomina] sise 
// 3^ between each pair of vertices is a repulsive force; this force is 
// significantly smaUer than the spring forces, and acts to keep 
// non atljaceni vertices ftom tlrifting close to each oUicr. 

// 4. allowing diese forces to act by moving the vertices causes an 
// approximate planar embedding of the graph 
// 5. the forces are implemented by a discrete simiiJation, we calculate 
// the forces on each point, tlien move all points simult:meous!y 
// to their new positions. 

// 

// Note: venices in different components do not act on each other 

H 

// Movement in each simulation step is damped to a limit. Some spring 
// embedders use a "temperature* setting to reduce tjie limit as the 
// embedding progresses, but we do not. 

If 

If We don't use any units for tlic force; if we measure a force of N, 
if that means we move the vertex N pixels in the direction t>f die 
ff force. 
ff 

//We always generate straight Unes l>etween vertices; the tlliallenge 
ff statement allows multi-segment lines. 

// 

//T!ie iteration terminaies when a steady-state appears to have been 
ff reached (that is, all the forces arc small),or when the number 
// of steps passes a limit.The limit is wimewhat empirkal; lai^e 
ff graphs tend to occupy an area proportional to the number of vertices 
// and therefore to have a width and heiglit proportional die die square 
// root of the number of vertices. Meanwhile the number of steps 
// required to move each vertex into place is probably proportional 
// to the width or height (because we limit the amount of nkweracnt on 
// each step) . Therefore the number of steps in the iteration is 
// roughly proportional to sqrt(number of vertices), and this is how 
// we set die iteration limit for large graphs. (For small graphs we 
// use a fixed limit.) 

// 

// For the spring forces we me a Htiokc’a law: 

// 

// force = const * unit vector * (nominal length ■ distance); 

// 

// if the distance is greater than nominal, the tbree 
// vector ptiiitts toward the other ix>int, meaning the 
U spring is stretched and we are going to move toward the 
if other point. 

//The Hooke s [aw constant reprcsents what fraction of 
// the distance to the nominal state we would like to 
// move in one step; therefore it is necessarily U-Ss 
// than 1. Note also titat if dierc are sevemi vertices pulling a 
// vertex in the same direction, the resultant force may Ive very^ 

// largejaigc enough to cause the vertex to overshoot the iiptimal 
// ixisilion.This wouldn't happen widi real spring.^, because the 
11 forces continually change as the particles nxive. but it is an 
// artifact of our discrete simulation. We attempt to work arouml 
// this by keeping die Htnike's law constant small. So that even if 
// diere are scvenil vertices, die force will not become excessslve. 

//This has the drawback that convergence may be slow, (llie llixikes 
// law constant can alstj be thought of as a gain in this system.) 

//A similar problem Is that when two venices are connected, they 
// pull each tiiher. arLd the resulting force may actually ptill them 
if past c“adi other, which would lead to aseillation.Again we try to 
ff avoid this by using a small Hooke’s law constant. 
ff 


if For all vertices there is a repulsive hiree between pairs of 
// vertices. We use an inverse .square law: 

// 

// force = coast ‘ unit vector / (distance ^2) 

// 

//Tlie repulsive constant shentid be chosen so that it causes 
// a signiMeant force (that Is, one greater than w^e would 
// stop itemiing at) when points arc ckiscr th^in the nominal 
// distance. So for example if die insignUlcant force is S, 

// and the nominal distance is 100, we would pick the 
ff constant to lie 5 * liMP2. 

//Tlie repulsive force is suptxjsed to be a gentle force dial wall 
// cause nearby point,s to pivot away from each other, so w^c 
// will ebmp die amount of the force that can be applial 
// in one move.This avoids generating a ridiculously large 
// force when points Jire very near each other. 

//The rcpulsfve fiirce is needed to keep f^-away portions 
if of the graph from loiating and overlapping each other 


// 


//The calculation of the repulsive force is by Ihr the skiwesi part 


// of the algorithm, because it is a OCn^2) process (each pair of 
// vertices has to be considered. In contrast, if we assume a 
// bounded number of edges Incident to each vertex, the spring 
ff farce calculation Is only a CXn) process. 

ff 

fimmmifmiifiiimfm^^^ 
fi paametets controlling the spring embedder 

const float kMaxForeaSqunred = 200 * 200; //max force to apply in one 
step 

const float kSteadyStateForce = 5,0; ff stop if all fames less llitin this 
const float kSteadyStateForceSquared = kSteadyStateForce * 
kSteadyStatePoroe; 

const float kNominalLength = 100.0;//spring length.unilv; pixels 
const float kEooke “ 0.10:// Hooke's law constant (or gain) 
conet float kRapulslveConstant ^ 5 ‘ kNomlnalLength ‘ 
kNomlna iLength; // for inverse square law 

const float kMaxRepulslveForce “20,0; // limit oa amount of repulsion 


CGraphEmbedder: tCGraphEtnbedder (CMyGraph^i aGraph. 
int whichComponent) : 
fGraph[aGraph), 

fCoraponentNutnber(whichComponent] , 
fpSprlngFotcesX(0)* 
fpSpeingForeasYCO), 
fpPartlcleFi:ircesX(0}, 
fpRarticleForcesY (0) 
f 

int numVsrticen = aGraph*GfitNymVartices(,) r 
fpSprlngForcesX = new float [nuinVeirtices]: 
fpSpringFotceaY = new float[nunVertieeal : 
fpParticleForcesX - new float[num,Vertices] : 
fpParticleForcesY = new float[numVertices] ; 


CGraphETabedder:;-"CGraphEmb 0 dder() 

f 

delete [] fpSpringForeesX: 
fpSpringForcesX ^ 0; 
delete 1] fpSpringForcesY; 
fpSpringForcesY = 0; 
delete [] fpFatticleForceEX: 
fpParticleForcesX = 0; 
delete [] fpFarticleForcesY: 
fpPatticleForcesY “ 0; 


void CGraphEmbed der:;EmhedComponent() 

I 

int numVertices = fGraph.GetNumVerticesO; 
int maxiteratiOils “ 5 * 

at3tlc_east<int>{atd;:sqrt{numVErtices)); 
if {maxiterations < 50) 
maxlterations = 50; 

for (int 1=0; i ( maxlterations: i++) 

I 

//We splii upurt the spring and puriiLic Ibrces for 
// ex|>ermiental purposes. It turns out not to be 
// useful to run the particle forces part-time, so 
// we run them all llie time, 
bool hUsePartieleo ■ true: 

FindAllForces(bUaePartleles): 


// move aU vertices 

bool bSteadyState = true: 

for (int whlchVertex = 0; whlchVertex < numVerticea; 
whichYertex-H*) 


f 

if [fGraph,GetCotnponentNu]iiber(whichVsrtex) = 
f Comp onentNunibe r J 


float foreeX = fpSpringForcefiX.twhichVertex]; 
float forceY = fpSpringForcesYlwhichVertex]; 
if {bUsePartacles) 


forceX += fpFarticleFortesX[whichVertex]: 
forceY += fpFarticleForcesY[whichVertex] ; 

I 

float forceSquared = forceX * forceX + forceY * 

forceY; 

if {forceSquared )= kSteadyStateForteSquared) 
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bSteadyState ” false: 

float unitX ^ deltaX / distance; 
float unit? == delta? / distanee; 

// lirnii force if necessary 

if [fqrceSciiiared > kMaxForceSquared) 

1 

accuraForceX kHooke * unitX * (kNoininalLength - 

distance); 

const float kScaleFactor ^ 

std::sqrt{kMaxForceSquared / farceSqoared); 
forceX = forceX * kScaleFactar; 
forceY = forceY * kScaleFactor: 

L 

actumForcE? 't-= kHooke * unit? ‘ (kNominalLength ’ 
distance); 

1 

f 

r 

U now move the vertex 

Point aVertex ^ fGraph.GetVertex(whichVertex); 
aVertex.h += forceX: 
aVettex.v += force?: 
fGraph.EetVertex(whichVertex, aVertex): 

1 

*pForceX = accumFotceX: 

'pForce? = accumForce?: 

1 

void CGraphEinbedder::FiudOnEFartlcleForcE(Int centerVettex, 
float ^pForeeX, float *pForceY) 

1 

] 

If {hSteadyState) 

f 

1 

ff Note: it is possible tliat the component has only one vertex 
if Note: it is possible tltat two venices are at the same point 

Point sVertex ^ fGraph^GetVertexlcenterVertex); 
int numVerticea ” fGraph.GetHumVerticeg(); 

break: //all done! 

1 

1 

1 

// force vector in the dirceiion we are going to move; 
float accumForceX “ 0.0, accumForceY = D.O; 

1 

void CGraphEinbedder;:FindAllForces(bool bFindPartlcles) 

[ 

for (int otherVertsx = 0; OtherVertex < numVertices: 
otherVertEx++J 

1 

int numVertices ^ fGraph.GetNuraVertices[): 
for fint whichVertex = Q; vklchVertex < numVerticea; 
whichVertex++) 

1 

if (otherVertEX = centerVertex) 

continue; // them's no forte fir^iu vertex to itself 

E 

if (fGraph .GetCompofientNumber (wh-ichVertex) = 
fCoraponentNumb e r} 

[ 

Point bVertex = fGraph.GetVertEx(otherVertex) : 
float deltaX ^ a Vert ex. h - bVertex.h: // point differences 
float deltaY ” aVertex.v • bVertax.v: 
float distanceSquarsd = dEltaX * deltaX + delta? * 

FindOneSpringForce(whichVertex, 
&fpSpringForceaX[which¥ertexl» 

^fpSpringForcesY[whichVertexj ): 
if (bFlndParticles) 

delta? ; 

If [distenceSquared < 1.0) 

distanceSquared = 1 , D : // just in case two ptdnts coincide 
float distance ^ std; : sqrt{distanceSqoared): 

FlndOneParticleForce{whichVertex ^ 

&fpParticleFoi:cesX[whichVertex] ^ 

&fpParticleForcEEY[whiohVertGx]) : 

] 

1 

1 

// unit vector pointing to us from other [xiint; 

// forces in this direct km cjmse us to move :iw:!y from 
// the other ptiini 

float unitX = deltaX / distance; 
float unit? = delta? / distance; 

J 

1 

void CGraphEmbedder;:FindOneSpringForceClnt centerVertex, 
float 'pForceX, float *pForceY) 

float repAinount “ kRepul siveConstant / distaticeSquared ; 
if [repAmount ^ kMaxHepulsiveForce) 
repAtnount = kMaxRepulfiivaForce; 
accumForceX +" repAniount * anitX: 

1 

// Note: it is possibJe tinii the componeju hits only one vertex 
// Note: it Is possible that two vertices sire at the same point 

Point aVertex = fGraph.GetVertex(centerVerteK) : 
iut namVErtices = fGraph.GetNumVertices (): 

// force vector in the direction we are goinji to move; 

// this acciimnbues the spring restoring forces of all points 
// acting on this point 

float accumForceX = 0-0, accumForceY ^ 0.0; 

accumForce^ repAoiourit * utiltY: 

1 

•pForceX = accumForceX: 

•pForceY = accumForce?: 

1 

////////////////////////////////////////////////////////////////////// 

// tlMviinph impletnenuition 
/////////////////////////////////////M^^^^ 

for (int QtherVertex = 0: otherVertex < numVertices; 
otherVertex++) 

CMyGraph::CMyGraph[int numVertices) ; 
fNuniVartices{numVertices) * 

1 

If {otherVeetex = centerVertex) 

catitiniie : // there's no force from vertex to itself 

fpAdjatencies (OJ , 
fpVertexPolnts(O), 
fljuinCcHgponents{0), 
fpCompojientNnmbers (0) 

// hir adjacent vertices, figure out the 
// restoring force due to the spring 

if { fGraph.AreAdjacEnt(centerVertGx, otherVertex) J 

[ 

1 

fpAdjacencies = new chardnumVertices * numVertices] ; 
std : ;memsetCfpAdjacencies. 0. 

nuxiVertices ^ numVertices * 

Point bVertex = fGraph.GetVertEx{otherVertex) ; 
float deltaX = aVertsx*b ” bVertex.h://point differences 
float deltaY = aVertex.v - bVertex.v; 
float distaneeSquared “ deltaX deltaX + deltaY * 

deltaY: 

if (distanceSquared < 1*0) 

distances quared = 1*0; //just in case two points coincide 
float distance = std :: sqrt(distanceSquared) ; 

si^eof ichar) ): 

fpVertexPoints = new Point[numVertices] ; 
std ;; meniset {fpVertexPoints. 0, numVertices * 
slzeof(Point) ); 

fpComponentNurabers - new int [numVertices] ; 
std : : meinset { fpComponentNucibe r s . 255 , 

numVertices * sizeof(Int) ); 

1 

// unit vector pointing to us fr!>m other point; 

// forces in tliis direction ciusc us to move away from 
if the other point 

CMyGraph: : "CMyGraph () 

! 

delete [] fpAdjacencies ; 
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Extend REALbasic with 


Advanced Plugins 


Spreadsheet Controls: 

We provide a wide range of spreadsheet controls for 
REALbasic, Including nnultistyled and custom rendering 
spreadsheet controls. 
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• More than 32k of rows. 

• Classic, OS X and Win32. 

• Accelerated for maximum 
speed. 

• Images in cells. 
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Cryptography: 

We provide data encryption, encoding, 
compression and hashing for REALbasic. 

Supported Algorithms: 

• Encryption: 

- e-CryptIt 

- BlowFish (448 bit) 
-AES(Rijndael)(256 bit} 

• Encoding: 

-e-Cryptlt Flexible 

- Base 64 

- BinHex 

- MacBinary IN 

- AppleSingle / Double 

- UUCoding 

• Compression: 

- Zip on Strings and streams (.gz) 

• Hashing and Checksums: 

-CRC32/Adler32 

- MD5 / HMAC_^MD5 
-SHA/SHA1 /HMAC__SHA1 


other Plugins: 

We have many other 
plugins for REALbasic, 
including plugins to do 
advanced MacOS 
Toolbox tasks and more 
custom Controls. 



Speed up developement and make 
more advanced applications 
by using plugins ! Get free demos 
at www.einhugur.com 



Einhugur Software 
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accounting software 



"Easy to set up, easy to use, 
and excellent support ftoni 
the developer." 

Five stars on VersionTracker.com 


* cash entry 
• invoicing 

• payroll 

• reports 


• account chart 

• address index 
• help facility 

$ 49-95 

Free 30 -day trial 

http: // home pa ge. mac .com/ idlewild/ CoronaUS. hqx 



A best friend for businessl 

p.o. box 3164 ■ newbeffi * oragon • 97132 
idewlld^mac.ccun 


Whistle Blower 

Enterprise server monifor and restart iitilify 
whistteblower«sentman*com 

Connect to and va//ofate the response from web servers^ 
cgi scripts and over 23 other types of servers. 

Send email pages and perform unattended restarts via 
MasferSwitch or PowerKey 

Shifts make sure that the person on coil when the server 
goes down is the one who gets the page. 

68k, PPC and Carbon 

Web based odminisfrofion lets you check on and restart 
your servers from anywhere. 

Customize your response to on outage with Apple Script 
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ftp> get pxFTP 


The power and stability of 
the command line... 

The ease of drag and drop! 



pxFTP 


Get it today at... 

PIDOG.COM 


From the maker of.. 

piDock 

^^TelnetLauncher 


7C 


piDog Software 



I Control up to 12 changers (4,800 music CDs) 

Control Any Brand Stereo Receiver - 

. . . ^1-: 

t Play MP3 and other Sound Fiies 
% ^ Pius much, much more!!! " 
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Cross-Platform HELP 
'Module for REALbasic 




Apple Help Viewer, Microsoft HTML Help, WinHeip.>.. Why waste ’ 
your precious devetopmeet time designing and compiling a 
different Help system lor each platform when you can easily use 
UniHelp for all of them? 

NO additional plugins or classes needed. Just drag the UniHelp 
module and its graphics folder into your REALbasic project, add 
a few lines of code, create your external help pages, and that‘s 
it - instant online help for your compiled REALbasic applications 
that looks and functions the same on Classic Mac, Mac OS X 
and Windows SS/NT/ME/ZOOO/XP 



KEY FEATURES: 

• Displays Both HTML and ASCII Text Files. 

• Supports URL Links, Relative Links, Anchors Si Email Links. 

• Parses More Than 20 HTML Tags, Including <IMG>. 

• Supports Images, Video and Audio (Mac only). 

• Built-In Search Engine. 

• Hierarchical Listbox Displays Your Help Table of Contents. 

• Customizable Listbox Icons, Window Titie, Start PagOi Font, 
Contents Sequencing, etc. 

• GUI Support for 6 Languages: English, Spanish, French, Italian. 
Portuguese and German. 

• Small Footprint: Since Your Help Pages are External, only the 
UniHelp Module is Compiled with Your REALbasic Applications. 

• Familiar Help-style Interface with Back, forward. Home, 

Copy and Print buttons. 

• Easy to Use & Royalty-Free! 

‘'UniHelp*' and "Electric Butterfly" are never mentioned anywhere 
on the UnIHeip interface, providing you with a full-featured genenc 
Help solution - your customers will think you built it yourself! 


Built-in Search Engine 



■elecjtric 

v.;: ^ bu tterff ly^^hl 


EE DOWNLOAD! 

:/^www,ebutterfly,cofn 
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iScr^nsaver 

\^esigner 

for Macintosh and Windows 



the world's only cross-platform 
screensaver design tool 

■ build both Macintosh and Windows screensavers 
with a single click, on whatever system* you are using/ 

• use any QuickTime movie forniat : 

Macromedia Flash, MPEG, Cinepak, MP3, Midi, AVI, DV Video... 

• include a hidden movie that can be unlocked 
with a registration code 

■ customize and fuliy-brand both Installers 
and Screensaver control panels with pictures and text 

• screensavers instaJJ without DLLs, extensions, or restarts 


s/n7p/e 

WYSIWYG 

editor 

supports 
interactive Ffash 
and QuickTime 

consistent 
cross-pla tform 
user interface 

try before you buy 
fuiiy functional 
online downloads 





http t/iScreensa ver. net 

email : info @ iScreensaver.net 


* supported systeiTis, as of November ZOOl, irniludej 
MadflSOSb OS S.6 to 9.2, Micnosoft Windows 9S/9S/Me, NT4/NT200t>/XP 





db Reports 


Printing database driven 
reports from yovir REALbasic 
project has never been easier. 



Powerful expressions with 
easy-to-use interface make 
this an indispensable tool 
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providing business solu 


Download a free demo today. 
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Play 


Create digital image compositions on 
your Mac, quickly and easily. 



For more information, 
email chris@crescendosw.com, or 

visit us today at www.crescendo5vir.com/ 
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fpAdjacencies - 0: 
delete [] fpVertexPoints: 
fpVertexPoints ^ 0; 
delete [] fpCaraponentNumbers; 
fpCamponentNumbere “ 0; 


void CMyGrapb::SetVertex(liit whichVerteK. const Pointi 
rPoint) 

1 

fpVertexPointstwhlchVertex] = rPoint: 

I 

Point CHyGraph; iGetVertex(±nt i/hlchVertex) const 

I 

return fpVertCKPoints [whichVertex] ; 

I 

int CMyGtaph:sGetNumVerticesO const 

f 

return fNinGVertlcesj 

} 

void CMyGraph::SetAdjacent(int aVertex, int bVertex) 

I 

// set both [3^b\ and [b,ai because die matrix b symmetric 
fpAdjacencies[aVertex * fNumVertices + bVertex] = 1; 
fpAdjacenciea[bVertex ' fNumVertices + aVertex] “ 1; 

I 

bool CMyGraph:: AreAdJacentdnt aVertex, int bVertex) const 

i 

// only have to test one of two symmetric entries 

return (fpAdjaceuciee{aVertex * fHunVertices + bVertex] ^ 
1 ); 

1 


void CMyGraph':: Fi ndConnectedCompouents {1 

I 

// we start at each vertex and recursively mark all the 
// vertices it is connected to, 

for (int vhiehVextex = 0: whichVertex < fNumVertices: 
whichVertex++) 

f 

if (fpComponentNumbers[whichVertnxJ = -1) 

t 

y/ start new connected component 
int thisMack ” fNumConiponenta: 

f KumCcuiiponentS’H -1 

fpComponentNumbers[wbichVertexl = thisKark; 
MarkConnectedVertices(whlthVettex^ thisMark); 

] 

i 

[ 

void CMyGraph:tMarkConnectedVertices(int whichVertex, int 
thisNark) 
t 

// exantine each connected vertex, if not already marked then 
// mark it and call ourselves lecursiveJy on it 
int rowOffset “ fMumVGttices * whichVertex; 
for (int col = D; col < fNumVertices: col++3 
( 

if (fpAdjacenciEE[rowOffset + col] && 
fpCompouentNumbers[col] — 1} 

i 

fpCompouGntNumbers[col] = thisMark; 
MarkConnectadVertices(col, thisMark); 

I 

I 


int CMyGraph; ;GetNuaiGomponents(} 

I 

return fNiutiComponents; 

1 

int CMyGraph;;GetComponentNumber(Int aVertex) 

{ 

return fpComponentMuiiiberB [fl-Vertex]; 

I 


CGraphEmbedder.c 

pp 

iiiiiiiiiiiuiiiiitiiniiiiiiiniiiiiiiiiitiiiitiiiiuiiiiiiiitiiitiit 

// 

// Graph Wind<3w^ 

//Written by Allen StengerJanuary 2002 
// 

//This draws the gnph in a window. 

// 

//This reads in the graph descriptions from file and creates a 
// document window with a drawing of the graph inside, it also takes 
// care of scrolling and redrawing the document window. 

// 

////////////////////////////////////////////////////////////////////// 

If^inciliJde ‘’GGraphWlndovr.h*" 

#include "SxChartApp.h" 

//include <f3trGam> 

//include <astream> 

static const Rect kPlcCllpRect = 10* 0, 32767* 32767); 

// Picture's clipping reel 

static const int kMaxZoom =1 « 8: 77 2^(max number of zoom outs) 

mmmmmmmimmimimimm 

// CGraphWUidow implementation 

///////////////////////////////////////////////////// 7 //////^^^ 

// class static variables 

std::vectOC<CGraphWindDW *> CGraphWindow;:fgGraphWindows: 

CGraphWindow:;CGraphWindow(LStream •pStream) : 

LWiudow(pStream)< 

fpGraphView(O) 

I 

// add ourselves to list 
fgGraphWindows.push_back{this}; 

// add a placeholder title to the Wlndowr menu 
// (we don't know our title yet) 

LMenu •pWindowHenu = 

LMenuBar; :GetCurrentMauuBac( J->FetchMenu{kWindowHENI]); 
pWindowMenu->InsertCommand( "■\p andJseMenuItem* 16000 

); 

LCommande r::SetUpdateCoHmiandStatus(t rue); 

1 

CGraphWindow::~CGraphWindow[) 

[ 

// remove cjurseives from Vtlndow menu 
LMenu * pWindowMenu = 

LMenuBat:iGetCurrentMenuBar{)->FetcbMenu(kWiiidowMRNU); 
std;:vector<CGrapbWindow *>::iterator itet = 
std;;lover_bQund(fgGrnphWindows.begin{)* 
fgGraphWindows^endC)* this): 
int itemNumber = iter * fgGraphVindows.begin() + 1; 
pWindowHenu" ^RemoveitemCitemNuinber) ; 

LConimander: ; SetUpdateCommandStatus (true); 

// remcjvc ourselves from list - 

// use erase-remove idiom (see MeyersJEflectivc STTf item 52) 
f gGr aph Wind ows,s r as e C 

std::remove(fgGraphWindows.begin(). 

fgGraphWindows.endO , this), 
fgGraphWindows * end()); 


void CGraphWindowT:FindCommandStatus{ 

CommandT inCommand, 

Eooleau& outEnablcd* 

Boolean^ outUsesMark. 

UIiitl6& outMark. 

Str255 outName) 

[ 
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ResIDT theMenuID; 

Slntlfe theMenuItem; 

If (IsSTTitheticCoiMiaDd {inComand. tbeMenuID. CheMetiuItem) 

&& 

theMenuID = kWitidowMEKU && theMenuItem > 0) 

[ 

// window aitr enabled; 

// place ehecknurk next to fronimc ist window; 

// supply tile window title because we didn't know 
// it at window creation time 

LWindoirf ^ pWindow = fgGraphVindows ItheMenuIteni -1] ; 

pWindowOGetDeseriptor (ontName); 

outEnabled = true: 

outUsesMark true; 

outHark noMark; 

if {pWindow = LTDesktop: :Fet€hTopRegular{}) 
outMark cbeckMark; 

1 

else 

I 

switch (inCommand) 

I 

case cmd_KooiiiOu.t: 

[ 

int zooml = fpGraphView->G€tZoonLFactor [): 
if (zooiiil < kMaxZoom) 
outlnabled = true; 

I 

break: 

case cmd_ZooiiiIn: 

t 

int zooi!i 2 = fpGtaphVieW'>GetZooiaFactor (): 
if (zooinZ > 1) 

outEnabled = true; 

f 

break: 

default: 

1 . 

LWiridow::FltidCominandStatus (inCooiniand. outEnabled * 
outUsesMark. outMark* outNatne) r 
I 

break; 

] 

] 

] 

Boolean CGraphWindow: iOheyCoBiffiand [ 

CommandT inCortunand, 

void* ioParam) 

I 

RealDT theMenuID; 

Slut 16 theMenuItem; 

Boolean crodHandled = true; 

if (IsSyntheticGonimandCiuCommandH theMenulD, theMenuIteml 

& & 

theMeuuID — kWindowMENU && theMenuItem > 0) 

[ 

// bring desired window to front 

CGrapbWlndow *pWindow = fgGraphWindows[theMenuItem - 1]; 
^Desktop::SelectDsskWindow(pWindqw): 

1 

else 

I 

switch (inCDEmnand) 

f 

case cmd_Zoo]3iOut: 

I 

int zoornl = fpGtaphVlew->GetZoo!iiFactQr() : 
fpGraphView->SetZootiLFactor(2 * zoomi): 

1 

break; 

case cind_ZoomIn: 

I 

int zocmZ = fpGraphVlew‘>GetZoomFactor(); 
fpGraphYiew~)SetZoo[t]Factor (zooiiiZ / 2); 

] 

break; 


default: 

1 

cmdHandled - LWindow::ObeyCoTiiiDand{InCommand, 

ioParam): 

1 

break; 

] 

] 

return cmdHandled: 

I 

void CGraphWindow;;FinishCreateSelf() 

I 

fpGraphView = static_caBt<CGr3pbYiew 
*>(FindPaneByrD(kGraphView)): 

// add attachment to Jiandling page up/down etc, keys 
AddAttachment(new LKeyScrollAttachmentCfpGraphYlew)); 

LWindow::FinishCreateSelf(); 

1 

// GGntphWindow impiementiition 

CGraphView:iCGraphViewCLStream *pStream) ; 

LViev{pStreaiEi) * 
fhPicture(O)* 
fZoomFactor(l) 

( 

fPicFrame.top = fPicFrame*left ^ 0; 
fPicFrame.bottom - fPlcFrame* right = 0; 

I 

CGraphView; :"'CGraphVlsw() 

I 

if (fhPlcture} 

::DisposeHandle£reinterpret_cafit<Handle>(fhPlcture]); 
fhPicture = Or 


void GGrapbView:iLoadGraphtint testNumber) 
fFileNumberString = 

SxCbartApp: :TestMuiiiberToString(testNumbet}: 

// How WL- will handle the unknown picture si-ie: 

// we don't know yet die aeitial extent tif the graphs so 
// we ll use a big source and dipping rectangle, but 
U we ll alH] keep track of the actual size needed. 

//Then well set the view's image size to the actual size. 

// However we will draw Lnio the kirge sized area to avoid 
// scaling tlie picture. 

//We assume the graph will alway start somewhere neiu^COj)), 
// so dial will be our view's initial top left display 
// even if diere’s no data around there. 

OpenCPlcParams niyOpenCPlcParaais; 
inyOpeuGPlcParams*srcRect ^ kPicClipRect; 
myOpenCPicParamn,hRes = 0x00480000: 
myOpenCPicPacams.vRes “ 0x00480000: 
myOpenCPicParams.version = 2; 
myOpenCPicParams.r^servedl = 0; 
myOpenCPicParams.reservedZ = 0; 
fhPicture = : :0peuCFicture£&my0penCPlcParatiis); 

// set up Piet Lire die way we want it 
:; ClipRect (j^kPicClipRect) ; 

;;PenMarmai(); 

TextFont (1): // appiiciiLioti foni 
TextFaceCO): //plain 
TextMode(srcCopy); //plain 
Text Si ze f 9): // 9 piml 

DrawEdge.5 C) : 

DrawNamas(): 

::ClosePicturs(); 
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My files are 
important. 

Very important. 

I only share my 
files with those 
I tmst. 

I trust DAVE. 


Mac to PC, PC to Mac. Cross-platform 
file and print sharing is too vital 
to your business to risk. Trust 
Thursby, the company with 15 years 
experience. Trust DAVE, the solution 
with a proven track record. Share 
files and printers across a network 
with no barriers. DAVE installs on 
your Mac with no additional software 
required for the PC. It's fast, secure 
and easy to use. Download a free 
evaluation today I 



MacMni 


www.thursby.com 

MiK I? a trademaflt of Apple CompirtBrj. Inc. registeir^;d Irt the U,S. 
and i^her countries^ The for Mac OS X" araphic Is a trademark 
of AppEe Computer, Inc., used under Ihjehse. 

DAVE is a registered trademark or Thorsby Software Systems, Inc, 

© 2002, Thursby Software Systems, Inc. 









U make image the size of the usefui parts of ttie pkttire 
ResiselmageToC 

(fPicFrame.right - fPicFrame.left) / fZoomFactor. 
(fPicFrame.bottom ^ fPicFrame.top) / fZoomFactor, 
false)■ 

// force redraw now that we have something to draw 
Refresh[); 


void CGraphView::DrawSelfC) 

f 

// code swiped from Llhcturc::DrawSelf; we don't use 
// LPiciure because it requires the picture to be in a resom'e 
if [fhPictyre 1= nil) 

1 

Roct destRect ^ kPicClipRect: 
destRect.top /= fZoomFaetor: 
destRect.left /= fZoomFactor; 
destRect.right /“ fZoomPactor; 
destRect i bottom H fZooaiFactor; 

::DrawPicture(fhPicture, fiidestRect}: 

1 

else 

I 

Rect frame; 

CalcLocalFcameRect(frame); 

:: PenNortnal (): 

Pattern ItGrayPat: 

::MacPillReci[fiiframe* 

UQDGlobals:iGetLightGrayPat(^ItCrayPat)J : 

:: MacFratoeRect (&f tame); 
i 
I 

void CGraphView:tSetZoornFactor(int factor) 

I 

// attempt to send I to tlic same center after zooming 
SDimensionlb frameSize; 

GetFrameSise[frameSiael ; 

SPoirit3 2 imageLocatlon; 

GetlmageLocatlotiiimageLocatlon) \ 

SPolnt32 viewGentet: 

viewCenter.h ^ -imageLocation^h + IframeSize.width / 2J: 
viewCenter.v “ *imageLocation*v + (frameSize.height / 2); 
vlewCenter.h *= fZaomFactor; 
vifiwCenter.v *= fZoomFactor; 

// now do the imm 
fZoomFactor = factor: 

ResizelmageTof 

(fPicFrame. fight • fPlcFrarae. left) / fZooniFactor * 
(fPicFrame. bottom fPlcFrame . top) / fZooisFactor, 
false )3 

if try to re<en[tT 

viewCenter.h fZoomFactor: 
viewCenter.v /“ fZoamFactor; 

imageLocation.h = (fratneSize^width / 2) - viewCenter.h; 
imagoLocation.V ^ fframeSiza.height / 2) - viewCentet,v: 
EcrollPinnedIi]iageTo(-iti]ageLocation.h, -ImageLocation, v» 
false): 

Refresh 0 : // redraw ourself 


Int CGraphVlew::GetZoomfactorf) 
\ 

return fZooinPaetcr; 


void CGraphViev::DrawEd ges{) 

( 

// open ctjTxea segments file 
std: :ostringstreani fileNameStream: 
flleNameStream << “segments" << fPileNumberString 
". out": 

std::strlng fileName(flleNameStream.Etr[)): 
std:;ifstream segmentsStream(fileMarae.c„str()); 
if (!segmentsStream.ia_open[)) 


SxChartApp; :SayFileErrcir (fileName); 
return; give up 


// file fiirmat is: several blocks of form 
y/ number of points 
// point 1 horiz.poim i vert 

y/ ... 

If retd all blticks 

while ([segmentsStream.eof0) 

I 

yy read number of points in block 
stditstcing numPtsString: 
std:igetlineisegmentsStream, numPtsString); 
itit numPts ^ std: tatoifnumPtsString, c_str() ] ; 

// read all points in block 

for (Int i “ 0; i < nuniPts: i++) 

1 

std:3 string pointLine: 
std::getline(segmentsSt ream, pointLine): 
std:;string: ;si 2 e_type firstComma 
pointLine.find ['►'}: 

std::string horlzString ” pointLine.substr{0, 
firstComma)j 

std::string vertString = pointLine.substr(firstComma + 

1 ): 

Point aVertaje; 

aVertex.h ^ std::atal(horl 2 Strlng.c_str{)): 
aVertex.v = std;:atoi(vertString.c_str()) i 

// draw' segment 
if (i = 0) 

; :MoveTo(aVertex.h, aVertex.v); 
else 

::LlneTo(aVertex.h. aVertex.v): 

] 


void CGraphView: :DrflwNaitLes() 

[ 

yy wc also keep a running set of hounds tlie vertices 
in t maxH = 0; 
int laaxV = 0: 

yy open correct locations file 

std: lostringstream flleKaraeStceapi: 

fileNameStream << "locations" « fFileMuraberString << 
“.out"; 

std::string fileNametflleNameStream.strO J : 
std::ifstream locationsStreamCfileName.c_Btr()); 
if (I lQcationsStreaiii.is_open()) 
f 

SxChartApp::SayFileError[filename): 
return : // give up 

I 

// fde format is: several blocks of fcinra 
yy poinilK >ri z, pointvert, perstjrmame 

yy read all lines 

while (IlocatlonsStrsam.eof0 J 

I 

std;:string pointLine; 

std::getllne(locationsStream. pointLine): 

std::string:3slze_type firstComma = pointllnE.find( \ : 

std: :string: :f!i 2 e_type secondComma = 

pQlntLine.find('.'. firstComma +1); 
std::string horizString = pointLine.substr(0, 
firstComma); 

std::string vertString = 

pointLine. subatr (fltstCotnma + 1, second Comma ■ 
firstComma - 1): 

Std::string peraonName ^ pointLine,substr[secondComma + 

1 ); 

Point aVertex: 

sVertex.h = std::atoi(borizString.c_stc()); 
aVertex.v “ std::atoi[vertString.c_str()): 


92 


MacTfx:h • May 2002 





// draw name ai vertex, attempt to center on the vertex; 
if do not draw Id i of or ilwve 0. 

const int kCharHnlfHeight ^ 5; //assuming 9 poini type 
const char ‘pPersonStrlng ^ psrsonNaitie .c_str(): 
size_t nameCharLen ^ personName* length(); 
int nameWidth = ; ^TextWldth[pPersojiStriog^ 0, 
nameCharLen]: 

// width in pixels 

aVertex.h -= (nameWidth / 2) J 
aVectex-v += kCharHalfHeight; 
if (aVertex^h < 0) 
aVertex.h = 0; 

if (aVertex.y ( 2 * kCharHalfHeight] 
aVertex.v = 2 * kCharHalfHeight: 

; :McjveTo(a¥ertex*h* aVertex^v ): 

:;MacDrawText(personName.e_str0 , 0* 
perEonName,length()); 

// uptUte txnmtte 
if (aVertex.h > maxH} 
maxH = aVertex.h; 
if (aVertex^v > maxV) 
maxV = aVertex.v; 

I 

// uptlatc tM)unding reel - we somewhat arbitrarih' pad it 
// to nvokl having the labels clipped off 
const int kPadding = 100: //units: pixels 
maxV kPadding: 
maxH +” kPadding: 

Rect tempRect ^ (0. 0, maxV. maxH): 
fPicFrame = tempRect: 


xChartApp.h 

IllllltlllltlllllllltlllillllllllllllllltlllillllllltlllllllltillltIV 

t! 

ff S-xChan (MaeTech Prognunmer’s Challenge, Febniar)^ 2002) 
//Written by Allen SteniprJanuary 2002 
//This file includes ptiitions of: 

// ClksieApp.h, ®199'i-2(Kll Metrowerks Inc, All rights resented, 
// 

////////////////////////////////////////////////////////////////////// 
^pragma once 

^include <LApplication.h> 
i^include <string> 
j/lnclude (vector) 


victual void FindConmandStatiiEf 

CorainandT inCommand. 

Boolean^ outEnahled, 

Booieanfi! outUaesMark^ 

lJIntl6& outHark, 

Str255 outMame): 

// utility to convert a test number to a 2<harieter string 

Static std:ratring TestNumberToString(int teatNumber): 

// utility' to say wc got a fSk error 

static void SayFileError(const stdr:string irFilEName); 
protected: 

void RegisterClaaaes(): 
private: 

// used in implementation 
void RunAllTestaO : 

// irad in :dl tests from file and run them 
void RunAndLog {.int startCase, Int endCase) i 
// run rests startCase-endCase and log times 
void RunOneTestdnt testNumher): //run one test 
bool AskForTEStNumber(int *pTestNumbEr); 

// get test number, returns false if user cancels 
void DrawGraphCint testNurober); 

// ereate and lili graph w'lndow 


// class for running one test 
class CTestRunner 
[ 

public: 

explicit CTestRunner (Int testNuinber): 

“CTeEtRunner0; 

bool LoadtJames () : //returns inre if loaded OK 
bool LoadHookups () : // retunts hue if k>adfid OK 
void KakEEmbeddedGraph(): 
void WrltoLocatlons(}: 
void WriteSegpentsO : 

private: 

// used in impiemen tatkm 

void LoadOneHookup [const std :; string^! rHookupLlne): 
void FlndComponentBounds(Itit whichComp< Rect •pGompBounds); 
void MoveComponent(int whichCorap, int offaetH, int 
offsetV): 


// our et}mmands 
static const CoramandT 
All Tests 

static const CommandT 
static const ConnnandT 
static const ConunandT 
static const CommandT 


crad_RunAllTeEts = 2000: //FiloRud 

cmd_Run0neTest = 2002://File> Run One Test 
cind_DravGrsph ^ 2001: //File> Draw Grjph 
cmd_Zooipln = 2010: //2iooni> Zoom Tn 

emd^ZoomOut = 2011: //Zoom> Zoom Out 


// our ReslDs 
static const RcslDT 
static const ResIDT 
lest number 

static const PatielDT 
static const ResTDT 
static const PanelDT 
static const ResIDT 
static const Par^elDT 


kWindowMENU = 113 ; //Window menu 

kAskTestNumberDLOG = 1000 : //ai^k for 

kAskTcstNurtberEditPane ^ 3: //edit pane 

kGraphWindow = 1001: //graph window 

kGraphView “ 1: // display pane in graph window 
kBlankALRT = 1002: // Alert - fill in text 

kALRTTextPane = 1: // fill in text for above 


class CMyGraph: 

class SxChartApp : public LApplication ( 


// member variables 

std:: stririgfFileNuinbcrString: // holds suffix for this test e,g., *^01’' 

int fNumVErtices: // number of vertices = number of names 

int f N umH o oku p s : // number of hnnkups 

std::vector<std::string) 

fKames; // person names, sorted alphabetically 

CM y Graph ' f pGraph: // graph being embedded; created by LoadNatnee 

] ; 


CGraphEmbedder.h 

iiiiitiiiiiiiiiiiittiiiiiiiiiiiitiiiiiiiiiiiiiiiiiiiitimnii/iiitiit 

li 

// Clruph Embcddcr 

//Written by Allen Stengerjanuarv 2002 

// 

////////////////////////////////////////////////////////////////////// 
//pragma once 
class CMyGraph; 


public: 
virtual 


SxChartApp{): 

""SxChartApp(): 


virtual Boolean ObeyCominand( 

CoimnandT inCornmand ► 

void* ioFaram = nil): 


////////////////////////////////////////////////////////////////////// 

// ihhi dasii: implements a graph embedder 

class CGraphErnbadder 
I 

public: 

CGra.phEmbedder(GMyGraphs aGraph, int whlchComponent); 
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■^CGraphEflibedder’(); 


CGraphWindow.h 


void Embed C ompo nent()i 
privates 

U used ui implementation 

void FindAllForces[bool bFindParticles): 

// find resultant foree of all points acting on one vertex 
void FindOneSpringFQrGe(int centerVertex, 

float ‘pForeeX, float ‘pForceY); 
void FindOueParticieForceflnt centerYertex* 
float ‘pForceX. float ‘pForceY)j 

iiuifimmmiuim 

11 member variables 

CMyGtaphf! fGrapb; H graph being embedded 

Int fComponen tNnmber: if which component to embed 

// forces, indexed by vertex number 
float 'fpSpringForcesX; 

float *fpSpringForcesY; 

float *fpParticleForcesX; 

float ‘fpParticloForcasY' 

1 : 

////////////////////^^^^^^^ 

//This class is how die graph gets passed in and out of the em[>cddcr 
// it Is essentiaUy an adjacency maLrix along with a set of PoinLs 
// for each vertex. Vertices are numbered D to numVertices - 1. 

// We also maintain information on the connected componenLS of the 
// graph. 

class CMyGraph 

I 

public: 

explicit CMyGraph [int nuiaVertices) : 

'’CMyGraph 0 ; 

void SetVertex(itit whichVertex, const Points rPoint) : 
Point GetVertex[int whlchVertex) const: 
int GetNujnVertices() const: 

// we deal with nntlirected graphs: setting a adjacent to b 
// also makes b adjacent Uj a 

void SetAdjacentCint aVertex, Int bVertex): 
bool AreAdjacont(int aVortex* int bVertex) const: 

// accessing the components, i t., the connected subgraphs 
void Find Conner tedCompanents {);// scan graph, determine compnnenb 
int GetNuatCoinponentfi [): // number of components 

int GetComponentNimiber (int aVertex): //this vertex's compmenrs 
number 

prlvata: 

// used in implementation 

void MarkConnectedVerticea(int whichVertex^ int thlsMark): 
// member variables 

lilt fNunVertlces: If number of vertices in graph 


////////////////////////////////////////////////////////////////////// 

If 

// Graph Window 

// Written by Allen Stengerjanuary 2002 

// 

//This draws the graph in a window. 

// 

////////////////////////////////////////////////////////////////////// 

#pragma once 

i^include <string> 

^include <vector> 

class CGraphVlew; 

////////////////////////////////////////////////////////////////////// 

// class for window holding a graph 
////////////////////////////////////////////////////////////////////// 
class GGraphWindow : public LWindov 
j 

public: 

enura t class_ID - F0UR^CF1AR_C0QE f' GGWN') I: 

GGraphWindow(LStraara "pStream); 
virtual ^CGraphWitidowi); 

// overrides 

virtual void FindCotniitandStatus ( 

Comma nd T inC oirraian d. 

Boolean^ outEnabled, 

Boolean^! cutUsesMark, 

UInti64 outHark. 

Str25& outName): 

virtual Boolean ObeyCommand( 

CotnmandT inCominand, 

void* loPatam = nil): 

protected: 

// overrides 

virtual void FinishCreateSelf(): 
private: 

CGraphView * fpGraphView : // our graph view 

// list of all our windows, in creatkm order; 

// used for Window menu 

static Etd::vector<CGraphWindow *) fgGraphWlndovs: 

1 : 

////////////////////////////////////////////////////////////////////// 

// class for a scrollable view holding the graph 
////////////////////////////////////////////////////////////////////// 
class CGraphView : public LView 
1 

public: 

enmn { class.TD - FOUfLCHAR_CODE [' GGVW*) f; 

CGraphView[LStraam ’pStream): 
virtual -CGraphView(J : 


// the adjacencies matrix Ls symmetric, and we store Ixjth entries 
// (*fpAdjacendcii)[iHjJ ^ (1 or I as vertices i and j are 
// adjacent (have an edge connecting them) or not. 

// Note; a vertex is never adjacent to itself, 
chat ‘fpAdJacencias; 

// the vertices, indexed by vertex number 
Point ‘fpVertexPoints: 

// w^hich component each vertex is in, indexed by vertex number 
//'Hie value is a mimber from 0 through nnrti compimenis -1; 

// giving tlic component number. Initially all vtducs are -1. 

Int fNumCoiiiponentB: 
int 'fpComponentNumbers: 


void LoadGraph{lnt testKutnber) ; 
virtual void DrawSelf (): //override 
// :!t>om access 

void SetZoomFactorClnt factor): 
int GetZoomPaertpr () : 

private: 

// used in implementation 
void DrawEdgesO : 
void DrawSatnesO : 

// member variables 

PicHandle fbPicture: //picture holding our graph 
Reel f PicFrame: // extent of picnire with drawable data 

std:: stringfFilaNmnberSt cing: // file suffix^ e.g., “OF 

int f ZoomFacto r: // 2^n if zoom out n times 
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The below news headlines recendy crossed our news desk. For more information on 
each of these items, check out the MacTech web site <http://www.mactech.com> and 
search out the l>elow headlines from the home page. 


acgi dispatcher for Mac OS X 
Griffin releases versions 1.1 
Pow^erMate software for Mac OS X 
Monkeybread REALlTasic Plugin 
Collection 2A 

Troi Grabber Plug-in 1.5 for 
FileMaker Pro 5.5 

JCliecker 3.0.2: HTML Source code 
Editor with HTML Checker 
Power On Beefs Up Security With 
New On Guard for Macintosh 
XLK8 Releases Interview 2.0, First 
USB Analog Video Capture for X 
IFNeiMonitor 1.0 for OS X 
Coderus Limited Unveils ’'MacDX" for 
Mac OS X 

Pooch 1.2 Extends Its Support 
Big Nerd Ranch Launches Extreme 
Mentoring On-Site Training 
XEALbc 1,0 

F-Seripi 1.2 For Mac OS X 
PTF^s DOSSIER series is now up to 
14 volumes 

4D v6,8 Native on Mac OS X and 
Windows XP 

MacsDesign Studio Releases Web 
Help Desk 5,5 

Steve Jobs to Kick Off Apple's 
Worldwide Developers Conference 
Optigold ISP 2,9 J 
CURLHandle 1.5 released 
Will Co.sgrove Releases REALbasic 
plugin tor Speech Recognition 
FileMaker Developer Conference 
2tX)2 Set for August 12-15 
PocketBackup 1.0 
Bains Software Releases New 
Versions of MacDICT and 
SnapperHead 

BitVice MPEG2 video encoder: 
Professional Decoding, Consumer 
Price 

Trinfinity Releases Time Trick 1.1 For 
Macintosh And Windows 
Runtime Ships Revolution 1.1.1, New 
Pricing 

Iceblink Scjftware Releases 
[info]Batcher Classic 


• PC-Mac-Net FileShare v!,5 Streamlines 
File Transfers 

• Now Up-to-Date Ccmtact 4.2: Offers 
Backup and New Palm Support 

• VideoClix 2,0: Building in Interactive 
Objects 

• Freakin' Magic for FileMaker Pro: 
Accelerate your 4D WebSTAR 

• Sambucus v2,0O: Time Management 
Application 

• Snard vl.O Released 

• Ihidio Poster 1.0 

• Aladdin Ships Secure Delete- The 
Digital Document Sliredder! 

• JTRANSIT v2.0 deploys ColdFusion 
applications to Mac OS X 

• Mac OS X Application allows Scripted 
Control of FronlBase DataBase 

• FileMaker Units Top 7,5 Million 

• Markxware Announces Quark 5,0 & 
InDe.sign 2,0 Support 

• eSellenite Supports REALbasic 
Development For Windows 

• LassDSites,com 

• St. Clair Software Updates Default 
Folder X 

• Dragon Burn: New- CD-Recording 
Software for Mac 

• WestCiv releases Layout Master IJ 
HTML + CSS web page layout 

• FlLTERiT4.lJ 

• MACWEBGOM - Palo Alto Mac Server 
Colocation Community 

• Cross-Platform HELP Engine for Your 
REALbasic Apps 

• Precision Plugin L5 for REALbasic, now 
with x86 support 

• Znippetixer-X version 1.4 

• MassTraasit Gains Improved Enciy^ption 
and Security Capabilities 

• Presenta Ltd. announces iGetier L8 

• Coiourfull Creations Releases Calendar 
Class for REALbasic 

• eOrdering Complete LO Online Store 
and Shopping cart creator 

• OpenLink Releases Universal Server for 
Web Serv ices 

• Berkeley Releases 802.1 lb DSSS 
Analysis System 

• Whistle Blower 3.0 for Mac OS X 





Cocoa 


Carbon 


DewD epflt^ouRSOurcet drtlie 

hoi^tliSwtfeclfTools! 

mmMevileiiot.com 



iiiim 
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The view from the top 



The possibilities are limitless with JBuilder^ the leading Java" development 
solution. 


Borland 


Take EJB development to the next level with an Intuitive visual designer. 
Rapidly develop and deploy J2EE™ e-business applications to multiple 
application servers including Borland® Enterprise Server^ BEA® WebLoglc,® 
IBM® WebSphere/ and iPlanef* Application Server. Develop and deploy 
applications on Windows/ Linux/ Solaris/“and Mac® OS platforms. Efficiently 
collaborate as a team with support for leading version control systems. Build 
data-driven Web applications using servlets^ JSP/“ and XML, 


View code in a dramatic new way with UML code visualization. Experience 
extreme productivity with refactor!ng^ unit testing^ and documentation tools. 


See for yourself at http://www.borland,com/new/]b6/5064.html 
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Made in Borland^ Copynght©20Cil Bortand Software Corporation. All rights resErved. All Borland brand and product names are trademarks or registered trademarks of Borland Software Corporation in the United States and 
otfier countries. Java and aft Java-based marks are tracfemarks or registered trademarks of Sun Mfcrosystems^ Inc. In the U.S. and other coutilries. All other marks are the property of their respective owners. * 1242‘}.7 
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CodeWarrior”* development tools are the #1 choree 
for professional Macintosh® developers. Now get 
ready for the encore. With the new CodeWarrior 
tor Mac OS v8, you can huild applications with 
both Cocoa® and the PowerPlant C++ frame¬ 
work, ali within one integrated deveiopment 
environment. And you can wrRe code quicker than 
ever before, because code-completion for C, C++, 
and Java" gives you fast access to prototypes and 
parameters. Choose CodeWarrior tools ~ and get 
ready for a great performance. 

To learn more or buy, visit 
www.metrowerks.com 


CodeWarrior 

Development Tools for Mac^ OS 


metrowerks 
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bn m U.S. andi'or other counties, uaciniosh, Mac and Oocira era trademarks antt/or ragisl^r»d tradamaitis of Apple Computer. Intx Java le a hadntark of 
Stin Microsystems. ALL RE5EflVE.fi. MI^7fi1A-MTC0t5O2 



